LPNSPLOOKUPSERVICEBEGIN-Rückruffunktion (ws2spi.h)
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 |
|---|---|
|
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 NSPLookupServiceNext 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 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. |
|
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). |
[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 |
|---|---|
| Für diesen Vorgang ist nicht genügend Arbeitsspeicher verfügbar. | |
| Mindestens ein Parameter war für diesen Anbieter ungültig oder fehlte. | |
| Der Vorgang wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der Namespaceanbieter diese Funktion nicht implementiert. | |
| 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. |
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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für