LPNSPV2LOOKUPSERVICEBEGIN Rückruffunktion (ws2spi.h)
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 |
|---|---|
|
Fragt die Hierarchie eines Anbieters im Gegensatz zur ersten Ebene ab. |
|
Gibt nur Container zurück. |
|
Gibt keine Container zurück. |
|
Gibt nach Möglichkeit Ergebnisse in der Reihenfolge der Entfernung zurück. Das Maß für die Entfernung ist anbieterspezifisch. |
|
Ruft den Namen als **lpszServiceInstanceName** ab. |
|
Ruft den Typ als **lpServiceClassId** ab. |
|
Ruft die Version als **lpVersion** ab. |
|
Ruft den Kommentar als **lpszComment** ab. |
|
Ruft die Adressen als **lpcsaBuffer** ab. |
|
Ruft die privaten Daten als **lpBlob** ab. |
|
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. |
|
Ruft die Abfragezeichenfolge als **lpszQueryString** ab. |
|
Ruft Informationen ab, einschließlich Name, Typ, Version, Kommentar, Adresse, Blob, Aliase und Abfragezeichenfolge. |
|
Wenn der Anbieter über zwischengespeicherte Informationen verfügt, ignorieren Sie den Cache, und fragen Sie den Namespace selbst ab. |
|
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. |
|
Gibt an, dass der Namespaceanbieter nicht autorisierende Ergebnisse für Namen enthalten soll. |
|
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. |
|
Gibt an, dass der Namespaceanbieter eine sichere Abfrage verwenden soll. Diese Option gilt nur für Namensabfrageanforderungen. |
|
Gibt an, dass der Namespaceanbieter nur bevorzugte Namen zurückgeben soll. |
|
Gibt an, dass der Namespaceanbieter die Adresskonfiguration zurückgeben soll. |
|
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). |
|
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 |
|---|---|
| Mindestens ein Parameter war für diesen Anbieter ungültig oder fehlte. | |
| Der Name wurde in der Datenbank gefunden, enthält aber nicht die richtigen zugeordneten Daten, für die aufgelöst wird. | |
| Der Dienst ist unbekannt. Der Dienst kann nicht im angegebenen Namespace gefunden werden. | |
| 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 |