LPNSPV2LOOKUPSERVICEBEGIN Rückruffunktion (ws2spi.h)

Artikel
03/04/2024

Die NSPv2LookupServiceBegin-Funktion initiiert eine Clientabfrage eines Namespace-Dienstanbieters der Version 2, die durch die In einer WSAQUERYSET2-Struktur enthaltenen Informationen eingeschränkt wird.

Syntax

LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;

INT Lpnspv2lookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSET2W lpqsRestrictions,
  [in]  DWORD dwControlFlags,
  [out] LPVOID lpvClientSessionArg,
  [out] LPHANDLE lphLookup
)
{...}

Parameter

[in] lpProviderId

Ein Zeiger auf den Bezeichner für den zu abfragenden Namespacedienstanbieter.

[in] lpqsRestrictions

Ein Zeiger auf die Suchkriterien. Siehe Hinweise.

[in] dwControlFlags

Eine Reihe von Flags, die sich auf die Suche auswirken. Dieser Parameter kann eine Kombination der folgenden Werte sein, die in der Winsock2.h-Headerdatei definiert sind.

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 NSPv2LookupServiceNextEx 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 NSPv2LookupServiceNextEx 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).
LUP_DISABLE_IDN_ENCODING 0x800000	Gibt an, dass der Namespaceanbieter die automatische Codierung internationaler Domänennamen deaktivieren soll. Dieser Wert wird auf Windows 8 und Windows Server 2012 unterstützt.

[out] lpvClientSessionArg

Ein Zeiger auf die Clientsitzung.

[out] lphLookup

Ein Zeiger auf das Handle, das in nachfolgenden Aufrufen von NSPv2LookupServiceNextEx 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 (d. h. 1) zurückgeben, wenn bei der Routine ein Fehler auftritt und der entsprechende Fehlercode mithilfe von WSASetLastError festgelegt werden muss.

Fehlercode	Bedeutung
WSAEINVAL	Mindestens ein Parameter war für diesen Anbieter ungültig oder fehlte.
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.
WSA_NOT_ENOUGH_MEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um diesen Vorgang auszuführen.

Hinweise

Die NSPv2LookupServiceBegin-Funktion wird als Teil der Architektur des Namespacedienstanbieters Version-2 (NSPv2) verwendet, die unter Windows Vista und höher verfügbar ist.

Unter Windows Vista und Windows Server 2008 kann die NSPv2LookupServiceBegin-Funktion nur für Vorgänge auf NS_EMAIL Namespaceanbietern verwendet werden.

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

Die NSPv2Startup-Funktion wird jedes Mal aufgerufen, wenn ein neuer Clientprozess mit dem Namespaceanbieter beginnt. Anbieter können das Clientsitzungsargument verwenden, auf das der parameter ppvClientSessionArg verweist, um Informationen zu dieser Sitzung zu speichern. Wenn beim Aufruf der NSPv2Startup-Funktion ein Wert für das Clientsitzungsargument angegeben wurde, wird dasselbe Clientsitzungsargument im lpvClientSessionArg-Parameter an die NSPv2LookupServiceBegin-Funktion übergeben.

Wenn LUP_CONTAINERS in einem Aufruf angegeben ist, vermeiden Sie alle anderen Einschränkungswerte. Falls angegeben, 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, Container zu finden. Beispielsweise können alle Container 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 = NSPv2LookupServiceBegin(
    lpProviderId,
    lpqsRestrictions,
    LUP_CONTAINERS,
    lpClientSession,
    lphLookup);

gefolgt von der erforderlichen Anzahl von NSPv2LookupServiceNextEx-Aufrufen . Dadurch werden alle Container zurückgegeben, die sofort im Ausgangskontext enthalten sind. Das heißt, es handelt sich nicht um eine tiefe Abfrage. Damit kann die Struktur des Adressraums durch Durchlaufen der Hierarchie zuordnen und möglicherweise den Inhalt ausgewählter Container auflisten. Bei nachfolgenden Verwendungen von NSPv2LookupServiceBegin werden die Container verwendet, die von einem vorherigen Aufruf zurückgegeben wurden.

Erstellen von Abfragen

Die WSAQUERYSET2-Struktur wird als Eingabeparameter für NSPv2LookupServiceBegin verwendet, um die Abfrage zu qualifizieren. In der folgenden Tabelle sind **WSAQUERYSET2**-Membernamen aufgeführt, und es wird beschrieben, wie die **WSAQUERYSET2** zum Erstellen einer Abfrage verwendet wird. Member, die als optional gekennzeichnet sind und von den Anforderungen des NSPv2-Anbieters abhängen, können als **NULL**-Zeiger bereitgestellt werden, wenn sie vom Namespaceanbieter als Suchkriterien nicht verwendet werden. Weitere Informationen finden Sie unter Abfragebezogene Datenstrukturen.

WSAQUERYSET2-Membername	Abfrageinterpretation
dwSize	Wird auf sizeof(WSAQUERYSET2) festgelegt. Dies ist ein Versionsverwaltungsmechanismus.
lpszServiceInstanceName	Eine Zeichenfolge, die den Dienstnamen enthält. Die Semantik für das Wildcarding innerhalb der Zeichenfolge ist nicht definiert, kann aber von bestimmten Namespaceanbietern unterstützt werden. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpVersion	Die gewünschte Versionsnummer, die Die Semantik für den Versionsvergleich bereitstellt (d. a. die Version muss genau übereinstimmen, oder die Version muss nicht kleiner als der angegebene Wert sein). Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszComment	Dieser Member wird für Abfragen ignoriert.
dwNameSpace	Der Bezeichner eines einzelnen Namespaces, in dem die Suche eingeschränkt werden soll, oder NS_ALL, um alle Namespaces einzuschließen.
lpNSProviderId	Die GUID eines bestimmten Namespaceanbieters, der die Abfrage nur auf diesen Anbieter beschränkt. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszContext	Der Ausgangspunkt der Abfrage in einem hierarchischen Namespace. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNumberOfProtocols	Die Größe der Anzahl der Einträge im Protokolleinschränkungsarray in Byte. Dieser Member kann 0 (null) sein.
lpafpProtocols	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, was einen Wildcard-Wert bedeutet. Namespaceanbieter können Informationen zu jedem Dienst bereitstellen, der das entsprechende Protokoll verwendet, unabhängig von der Adressfamilie. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszQueryString	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. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNumberOfCsAddrs	Dieser Member wird für Abfragen ignoriert.
lpcsaBuffer	Dieser Member wird für Abfragen ignoriert.
dwOutputFlags	Dieser Member wird für Abfragen ignoriert.
lpBlob	Ein Zeiger auf eine anbieterspezifische Entität. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2spi.h

Weitere Informationen

AFPROTOCOLS

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceEnd

NSPv2LookupServiceNextEx

WSAQUERYSET2-Membername	Abfrageinterpretation
dwSize	Wird auf sizeof(WSAQUERYSET2) festgelegt. Dies ist ein Versionsverwaltungsmechanismus.
lpszServiceInstanceName	Eine Zeichenfolge, die den Dienstnamen enthält. Die Semantik für das Wildcarding innerhalb der Zeichenfolge ist nicht definiert, kann aber von bestimmten Namespaceanbietern unterstützt werden. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpVersion	Die gewünschte Versionsnummer, die Die Semantik für den Versionsvergleich bereitstellt (d. a. die Version muss genau übereinstimmen, oder die Version muss nicht kleiner als der angegebene Wert sein). Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszComment	Dieser Member wird für Abfragen ignoriert.
dwNameSpace	Der Bezeichner eines einzelnen Namespaces, in dem die Suche eingeschränkt werden soll, oder NS_ALL, um alle Namespaces einzuschließen.
lpNSProviderId	Die GUID eines bestimmten Namespaceanbieters, der die Abfrage nur auf diesen Anbieter beschränkt. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszContext	Der Ausgangspunkt der Abfrage in einem hierarchischen Namespace. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNumberOfProtocols	Die Größe der Anzahl der Einträge im Protokolleinschränkungsarray in Byte. Dieser Member kann 0 (null) sein.
lpafpProtocols	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, was einen Wildcard-Wert bedeutet. Namespaceanbieter können Informationen zu jedem Dienst bereitstellen, der das entsprechende Protokoll verwendet, unabhängig von der Adressfamilie. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
lpszQueryString	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. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNumberOfCsAddrs	Dieser Member wird für Abfragen ignoriert.
lpcsaBuffer	Dieser Member wird für Abfragen ignoriert.
dwOutputFlags	Dieser Member wird für Abfragen ignoriert.
lpBlob	Ein Zeiger auf eine anbieterspezifische Entität. Dieser Member ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.

Freigeben über