LPNSPLOOKUPSERVICEBEGIN-Rückruffunktion (ws2spi.h)

Artikel
08/28/2023

Die NSPLookupServiceBegin-Funktion initiiert eine Clientabfrage eines Namensdienstanbieters, die durch die in einer WSAQUERYSET-Struktur enthaltenen Informationen eingeschränkt wird.

NSPLookupServiceBegin gibt nur ein Handle zurück, das von nachfolgenden Aufrufen von NSPLookupServiceNext verwendet werden sollte, um die tatsächlichen Ergebnisse abzurufen. Da dieser Vorgang nicht abgebrochen werden kann, sollte er so implementiert werden, dass er schnell ausgeführt wird. Obwohl es akzeptabel ist, eine Netzwerkabfrage zu initiieren, sollte für diese Funktion keine Antwort erforderlich sein, um erfolgreich zurückgegeben zu werden.

Syntax

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

Parameter

[in] lpProviderId

Ein Zeiger auf den zu abfragenden Namen des Dienstanbieters.

[in] lpqsRestrictions

Ein Zeiger auf die Suchkriterien. Siehe Hinweise.

[in] lpServiceClassInfo

Ein Zeiger auf die WSASERVICECLASSINFO-Struktur , die Schemainformationen für den Dienst enthält.

[in] dwControlFlags

Ein Wert, der die Tiefe der Suche steuert.

Wert	Bedeutung
LUP_DEEP 0x0001	Fragt die Hierarchie eines Anbieters im Gegensatz zur ersten Ebene ab.
LUP_CONTAINERS 0x0002	Gibt nur Container zurück.
LUP_NOCONTAINERS 0x0004	Gibt keine Container zurück.
LUP_NEAREST 0x0008	Gibt nach Möglichkeit Ergebnisse in der Reihenfolge der Entfernung zurück. Das Maß für die Entfernung ist anbieterspezifisch.
LUP_RETURN_NAME 0x0010	Ruft den Namen als lpszServiceInstanceName ab.
LUP_RETURN_TYPE 0x0020	Ruft den Typ als lpServiceClassId ab.
LUP_RETURN_VERSION 0x0040	Ruft die Version als lpVersion ab.
LUP_RETURN_COMMENT 0x0080	Ruft den Kommentar als lpszComment ab.
LUP_RETURN_ADDR 0x0100	Ruft die Adressen als lpcsaBuffer ab.
LUP_RETURN_BLOB 0x0200	Ruft die privaten Daten als lpBlob ab.
LUP_RETURN_ALIASES 0x0400	Alle verfügbaren Aliasinformationen werden in aufeinander folgenden Aufrufen von NSPLookupServiceNext zurückgegeben, und für jeden zurückgegebenen Alias ist das Flag RESULT_IS_ALIAS festgelegt.
LUP_RETURN_QUERY_STRING 0x0800	Ruft die Abfragezeichenfolge als lpszQueryString ab.
LUP_RETURN_ALL 0x0ff0	Ruft Informationen ab, einschließlich Name, Typ, Version, Kommentar, Adresse, Blob, Aliase und Abfragezeichenfolge.
LUP_FLUSHCACHE 0x1000	Wenn der Anbieter über zwischengespeicherte Informationen verfügt, ignorieren Sie den Cache, und fragen Sie den Namespace selbst ab.
LUP_FLUSHPREVIOUS 0x2000	Wird als Wert für den dwControlFlags-Parameter in NSPLookupServiceNext verwendet. Durch Festlegen dieses Flags wird der Anbieter angewiesen, das letzte Resultset zu verwerfen, das für den angegebenen Puffer zu groß war, und zum nächsten Resultset überzugehen.
LUP_NON_AUTHORITATIVE 0x4000	Gibt an, dass der Namespaceanbieter nicht autorisierende Ergebnisse für Namen enthalten soll.
LUP_RES_RESERVICE 0x8000	Gibt an, ob sich die Hauptantwort im Remote- oder lokalen Teil CSADDR_INFO Struktur befindet. Der andere Teil muss in beiden Fällen verwendbar sein. Diese Option gilt nur für Dienstanforderungen instance.
LUP_SECURE 0x8000	Gibt an, dass der Namespaceanbieter eine sichere Abfrage verwenden soll. Diese Option gilt nur für Namensabfrageanforderungen.
LUP_RETURN_PREFERRED_NAMES 0x10000	Gibt an, dass der Namespaceanbieter nur bevorzugte Namen zurückgeben soll.
LUP_ADDRCONFIG 0x100000	Gibt an, dass der Namespaceanbieter die Adresskonfiguration zurückgeben soll.
LUP_DUAL_ADDR 0x200000	Gibt an, dass der Namespaceanbieter die dualen Adressen zurückgeben soll. Diese Option gilt nur für Dual-Mode-Sockets (zugeordnete IPv6- und IPv4-Adressen).

[out] lphLookup

Ein Zeiger auf das Handle, das in nachfolgenden Aufrufen von NSPLookupServiceNext verwendet werden soll, um das Resultset abzurufen.

Rückgabewert

Die Funktion sollte NO_ERROR (null) zurückgeben, wenn die Routine erfolgreich ist. Es sollte SOCKET_ERROR (–1) zurückgeben, wenn bei der Routine ein Fehler auftritt und der entsprechende Fehlercode mithilfe von WSASetLastError festgelegt werden muss.

Fehlercode	Bedeutung
WSA_NOT_ENOUGH_MEMORY	Für diesen Vorgang ist nicht genügend Arbeitsspeicher verfügbar.
WSAEINVAL	Mindestens ein Parameter war für diesen Anbieter ungültig oder fehlte.
WSAEOPNOTSUPP	Der Vorgang wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der Namespaceanbieter diese Funktion nicht implementiert.
WSANO_DATA	Der Name wurde in der Datenbank gefunden, enthält aber nicht die richtigen zugeordneten Daten, für die aufgelöst wird.
WSASERVICE_NOT_FOUND	Der Dienst ist unbekannt. Der Dienst kann nicht im angegebenen Namespace gefunden werden.

Hinweise

Wenn LUP_CONTAINERS in einem Aufruf angegeben ist, vermeiden Sie alle anderen Einschränkungswerte. Wenn welche angegeben werden, muss der Namensdienstanbieter entscheiden, ob er diese Einschränkung für die Container unterstützen kann. Andernfalls sollte ein Fehler zurückgegeben werden.

Einige Namensdienstanbieter verfügen möglicherweise über andere Möglichkeiten zum Suchen von Containern. Beispielsweise können Container alle von einem bekannten Typ oder einer Reihe bekannter Typen sein, sodass eine Abfrageeinschränkung erstellt werden kann, um sie zu finden. Unabhängig davon, welche anderen Mittel der Name des Dienstanbieters für die Suche nach Containern hat, haben LUP_CONTAINERS und LUP_NOCONTAINERS Vorrang. Wenn daher eine Abfrageeinschränkung angegeben wird, die Container einschließt, verhindert die Angabe LUP_NOCONTAINERS , dass die Containerelemente zurückgegeben werden. Ebenso sollten unabhängig von der Abfrageeinschränkung nur Container zurückgegeben werden, wenn LUP_CONTAINERS angegeben wird. Wenn ein Namespace keine Container unterstützt und LUP_CONTAINERS angegeben ist, sollte er WSANO_DATA zurückgeben.

Die bevorzugte Methode zum Abrufen der Container in einem anderen Container ist der Aufruf:

dwStatus = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

gefolgt von der erforderlichen Anzahl von NSPLookupServiceNext-Aufrufen . Dadurch werden alle Container zurückgegeben, die sofort im Startkontext enthalten sind. Das heißt, es handelt sich nicht um eine Deep Query. Damit kann man die Struktur des Adressraums zuordnen, indem man die Hierarchie durchläuft und möglicherweise den Inhalt ausgewählter Container aufzählt. Nachfolgende Verwendungen von NSPLookupServiceBegin verwenden die Container, die von einem vorherigen Aufruf zurückgegeben wurden.

Erstellen von Abfragen

Wie bereits erwähnt, wird eine WSAQUERYSET-Struktur als Eingabeparameter für NSPLookupServiceBegin verwendet, um die Abfrage zu qualifizieren. In der folgenden Tabelle werden WSAQUERYSET-Membernamen aufgeführt und beschrieben, wie das WSAQUERYSET zum Erstellen einer Abfrage verwendet wird. Wenn ein Element als (Optional) markiert ist, kann ein NULL-Zeiger angegeben werden, der angibt, dass der Parameter nicht als Suchkriterium verwendet wird. Weitere Informationen finden Sie unter Abfragebezogene Datenstrukturen.

WSAQUERYSET-Membername	Abfrageinterpretation
dwSize	Wird auf sizeof(WSAQUERYSET) festgelegt. Dies ist ein Versionsverwaltungsmechanismus.
dwOutputFlags	Wird für Abfragen ignoriert.
lpszServiceInstanceName	Optional. Die referenzierte Zeichenfolge enthält den Dienstnamen. Die Semantik für die Feldhalterung innerhalb der Zeichenfolge ist nicht definiert, kann aber von bestimmten Namespaceanbietern unterstützt werden.
lpServiceClassId	Erforderlich. GUID, die der Dienstklasse entspricht.
lpVersion	Optional. Verweist auf die gewünschte Versionsnummer und stellt die Semantik für den Versionsvergleich bereit (d.a. die Version muss genau übereinstimmen, oder die Version darf nicht kleiner als der angegebene Wert sein).
lpszComment	Wird für Abfragen ignoriert.
dwNameSpace	Bezeichner eines einzelnen Namespace, in dem die Suche eingeschränkt werden soll, oder NS_ALL, um alle Namespaces einzuschließen.
lpNSProviderId	Optional. Verweist auf die GUID eines bestimmten Namespaceanbieters und beschränkt die Abfrage nur auf diesen Anbieter.
lpszContext	Optional. Gibt den Startpunkt der Abfrage in einem hierarchischen Namespace an.
dwNumberOfProtocols	Die Größe der Anzahl der Einträge im Protokolleinschränkungsarray in Bytes kann 0 sein.
lpafpProtocols	Optional. Ein Verweis auf ein Array von AFPROTOCOLS-Strukturen . Nur Dienste, die diese Protokolle verwenden, werden zurückgegeben. Es ist zulässig, dass der Wert AF_UNSPEC als Protokollfamilienwert angezeigt wird, der einen Feldhalter bedeutet. Namespaceanbieter können unabhängig von der Adressfamilie Informationen zu jedem Dienst bereitstellen, der das entsprechende Protokoll verwendet.
lpszQueryString	Optional. Einige Namespaces (z. B. whois++) unterstützen umfangreiche SQL-ähnliche Abfragen, die in einer einfachen Textzeichenfolge enthalten sind. Dieser Parameter wird verwendet, um diese Zeichenfolge anzugeben.
dwNumberOfCsAddrs	Wird für Abfragen ignoriert.
lpcsaBuffer	Wird für Abfragen ignoriert.
lpBlob	Optional. Ein Zeiger auf eine anbieterspezifische Entität.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2spi.h

Weitere Informationen

AFPROTOCOLS

NSPLookupServiceEnd

NSPLookupServiceWeiter

WSAQUERYSET-Membername	Abfrageinterpretation
dwSize	Wird auf sizeof(WSAQUERYSET) festgelegt. Dies ist ein Versionsverwaltungsmechanismus.
dwOutputFlags	Wird für Abfragen ignoriert.
lpszServiceInstanceName	Optional. Die referenzierte Zeichenfolge enthält den Dienstnamen. Die Semantik für die Feldhalterung innerhalb der Zeichenfolge ist nicht definiert, kann aber von bestimmten Namespaceanbietern unterstützt werden.
lpServiceClassId	Erforderlich. GUID, die der Dienstklasse entspricht.
lpVersion	Optional. Verweist auf die gewünschte Versionsnummer und stellt die Semantik für den Versionsvergleich bereit (d.a. die Version muss genau übereinstimmen, oder die Version darf nicht kleiner als der angegebene Wert sein).
lpszComment	Wird für Abfragen ignoriert.
dwNameSpace	Bezeichner eines einzelnen Namespace, in dem die Suche eingeschränkt werden soll, oder NS_ALL, um alle Namespaces einzuschließen.
lpNSProviderId	Optional. Verweist auf die GUID eines bestimmten Namespaceanbieters und beschränkt die Abfrage nur auf diesen Anbieter.
lpszContext	Optional. Gibt den Startpunkt der Abfrage in einem hierarchischen Namespace an.
dwNumberOfProtocols	Die Größe der Anzahl der Einträge im Protokolleinschränkungsarray in Bytes kann 0 sein.
lpafpProtocols	Optional. Ein Verweis auf ein Array von AFPROTOCOLS-Strukturen . Nur Dienste, die diese Protokolle verwenden, werden zurückgegeben. Es ist zulässig, dass der Wert AF_UNSPEC als Protokollfamilienwert angezeigt wird, der einen Feldhalter bedeutet. Namespaceanbieter können unabhängig von der Adressfamilie Informationen zu jedem Dienst bereitstellen, der das entsprechende Protokoll verwendet.
lpszQueryString	Optional. Einige Namespaces (z. B. whois++) unterstützen umfangreiche SQL-ähnliche Abfragen, die in einer einfachen Textzeichenfolge enthalten sind. Dieser Parameter wird verwendet, um diese Zeichenfolge anzugeben.
dwNumberOfCsAddrs	Wird für Abfragen ignoriert.
lpcsaBuffer	Wird für Abfragen ignoriert.
lpBlob	Optional. Ein Zeiger auf eine anbieterspezifische Entität.

Freigeben über