WSALookupServiceBeginW-Funktion (winsock2.h)
Die WSALookupServiceBegin-Funktion initiiert eine Clientabfrage, die durch die in einer WSAQUERYSET Struktur enthaltenen Informationen eingeschränkt wird. WSALookupServiceBegin nur ein Handle zurück, das von nachfolgenden Aufrufen von WSALookupServiceNext zum Abrufen der tatsächlichen Ergebnisse verwendet werden soll.
Syntax
INT WSAAPI WSALookupServiceBeginW(
[in] LPWSAQUERYSETW lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
);
Parameter
[in] lpqsRestrictions
Ein Zeiger auf die Suchkriterien. Ausführliche Informationen finden Sie in den Hinweisen.
[in] dwControlFlags
Eine Reihe von Kennzeichnungen, die die Tiefe der Suche steuern.
Unterstützte Werte für den dwControlFlags Parameter werden in der Winsock2.h Headerdatei definiert und können eine Kombination der folgenden Optionen sein.
| Flagge | Bedeutung |
|---|---|
|
Abfragen tief im Gegensatz zu der ersten Ebene. |
|
Gibt nur Container zurück. |
|
Container nicht zurückgeben. |
|
Gibt nach Möglichkeit Ergebnisse in der Reihenfolge des Abstands zurück. Das Entfernungsmaß ist anbieterspezifisch. |
|
Ruft den Namen als lpszServiceInstanceNameab. |
|
Ruft den Typ als lpServiceClassIdab. |
|
Ruft die Version als lpVersionab. |
|
Ruft den Kommentar als lpszCommentab. |
|
Ruft die Adressen als lpcsaBufferab. |
|
Ruft die privaten Daten als lpBlobab. |
|
Alle verfügbaren Aliasinformationen werden in aufeinanderfolgenden Aufrufen von WSALookupServiceNextzurückgegeben, und jeder zurückgegebene Alias weist den RESULT_IS_ALIAS Flagsatz auf. |
|
Ruft die Abfragezeichenfolge ab, die für die Anforderung verwendet wird. |
|
Eine Reihe von Flags, die alle LUP_RETURN_*-Werte abrufen. |
|
Wird als Wert für den parameter dwControlFlags in WSALookupServiceNextverwendet. Durch Festlegen dieses Flags wird der Anbieter angewiesen, den letzten Resultset zu verwerfen, der für den angegebenen Puffer zu groß war, und zum nächsten Resultset zu wechseln. |
|
Wenn der Anbieter Informationen zwischenspeichert, ignoriert den Cache und fragt den Namespace selbst ab. |
|
Dies gibt an, ob sich die Prime-Antwort im Remote- oder lokalen Teil der CSADDR_INFO-Struktur befindet. Der andere Teil muss in beiden Fällen verwendet werden. |
[out] lphLookup
Ein Handle, das beim Aufrufen WSALookupServiceNext verwendet werden soll, um mit dem Abrufen des Resultsets zu beginnen.
Rückgabewert
Der Rückgabewert ist null, wenn der Vorgang erfolgreich war. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und eine bestimmte Fehlernummer kann durch Aufrufen WSAGetLastErrorabgerufen werden.
| Fehlercode | Bedeutung |
|---|---|
| Zum Ausführen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden. | |
| Mindestens ein Parameter fehlte oder ist für diesen Anbieter ungültig. | |
| Der Name wurde in der Datenbank gefunden, aber es wurden keine Daten gefunden, die den angegebenen Einschränkungen entsprechen. | |
| Die WS2_32.DLL wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup- aufrufen, bevor Sie Windows Sockets-Funktionen aufrufen. | |
|
Dieser Dienst ist nicht bekannt. Der Dienst kann im angegebenen Namensraum nicht gefunden werden.
Dieser Fehler wird für eine Bluetooth-Dienstermittlungsanforderung zurückgegeben, wenn keine Remote-Bluetooth-Geräte gefunden wurden. |
Bemerkungen
Der lpqsRestrictions Parameter verweist auf einen Puffer, der eine WSAQUERYSET- Struktur enthält. Mindestens muss der dwSize Member des WSAQUERYSET- auf die Länge des Puffers festgelegt werden, bevor die WSALookupServiceBegin-Funktion aufgerufen wird. Anwendungen können die Abfrage einschränken, indem sie andere Member im WSAQUERYSET-angeben.
In den meisten Fällen sollten Anwendungen, die nur an einem bestimmten Transportprotokoll interessiert sind, ihre Abfrage anhand der Adressfamilie und des Protokolls mithilfe der dwNumberOfProtocols und lpafpProtocols Member des WSAQUERYSET- einschränken, anstatt den Namespace im dwNameSpace Member anzugeben.
Informationen zu unterstützten Netzwerktransportprotokollen können mithilfe der EnumProtocols, WSAEnumProtocols, WSCEnumProtocolsoder WSCEnumProtocols32 Funktion erneut übertragen werden.
Es ist auch möglich, die Abfrage auf einen einzelnen Namespace zu beschränken. Beispielsweise würde eine Abfrage, die nur Ergebnisse aus DNS (nicht Ergebnisse aus der lokalen Hostdatei und anderen Benennungsdiensten) möchte, das dwNameSpace Mitglied auf NS_DNS festlegen. Beispielsweise würde eine Bluetooth-Geräteermittlung das dwNameSpace Mitglied auf NS_BTH festlegen.
Anwendungen können die Abfrage auch auf einen bestimmten Namespaceanbieter beschränken, indem sie einen Zeiger auf die GUID für den Anbieter im lpNSProviderId Member angeben.
Informationen zu Namespaceanbietern auf dem lokalen Computer können mithilfe der WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32oder WSCEnumNameSpaceProvidersEx32 Funktion abgerufen werden.
Wenn LUP_CONTAINERS in einem Aufruf angegeben ist, sollten andere Einschränkungswerte vermieden werden. Wenn eine angabe ist, liegt es an dem Namensdienstanbieter, zu entscheiden, ob diese Einschränkung für die Container unterstützt werden kann. Wenn dies nicht möglich ist, sollte ein Fehler zurückgegeben werden.
Einige Namensdienstanbieter können andere Möglichkeiten haben, Container zu finden. Container können z. B. von einem bekannten Typ oder einer Gruppe bekannter Typen sein, und daher kann eine Abfrageeinschränkung erstellt werden, um sie zu finden. Unabhängig davon, was andere bedeutet, dass der Namensdienstanbieter für die Suche nach Containern, LUP_CONTAINERS und LUP_NOCONTAINERS Vorrang hat. Wenn daher eine Abfrageeinschränkung angegeben wird, die Container enthält, verhindert die Angabe LUP_NOCONTAINERS, dass die Containerelemente zurückgegeben werden. Ebenso sollten unabhängig von der Abfrageeinschränkung, wenn LUP_CONTAINERS angegeben wird, nur Container zurückgegeben werden. Wenn ein Namespace Container nicht unterstützt und LUP_CONTAINERS angegeben wird, sollte er einfach WSANO_DATAzurückgeben.
Die bevorzugte Methode zum Abrufen der Container innerhalb eines anderen Containers ist der Aufruf:
dwStatus = WSALookupServiceBegin(
lpqsRestrictions,
LUP_CONTAINERS,
lphLookup);
Auf diesen Aufruf folgt die erforderliche Anzahl von WSALookupServiceNext Aufrufen. Dadurch werden alle Container zurückgegeben, die unmittelbar im Startkontext enthalten sind; das heißt, es handelt sich nicht um eine tiefe Abfrage. Damit kann man die Adressraumstruktur zuordnen, indem man die Hierarchie durchgeht und vielleicht den Inhalt ausgewählter Container aufzählt. Nachfolgende Verwendung von WSALookupServiceBegin verwenden die von einem vorherigen Aufruf zurückgegebenen Container.
Wie bereits erwähnt, wird eine WSAQUERYSET--Struktur als Eingabeparameter verwendet, um die Abfrage zu WSALookupBegin. In der folgenden Tabelle wird angegeben, wie die WSAQUERYSET- verwendet wird, um eine Abfrage zu erstellen. Wenn ein Parameter als (Optional) gekennzeichnet ist, kann ein NULL- Zeiger angegeben werden, der angibt, dass der Parameter nicht als Suchkriterien verwendet wird. Weitere Informationen finden Sie im Abschnitt Query-Related Datenstrukturen.
| WSAQUERYSET-Mitglied | Abfrageinterpretation |
|---|---|
| dwSize- | Muss auf sizeof(WSAQUERYSET) festgelegt werden. Dies ist ein Versionsverwaltungsmechanismus. |
| dwOutputFlags | Wird für Abfragen ignoriert. |
| lpszServiceInstanceName | (Optional) Referenzierte Zeichenfolge enthält den Dienstnamen. Die Semantik für die Wildcarding innerhalb der Zeichenfolge ist nicht definiert, kann jedoch von bestimmten Namespaceanbietern unterstützt werden. |
| lpServiceClassId- | (Erforderlich) Die GUID, die der Dienstklasse entspricht. |
| lpVersion- | (Optional) Verweise auf die gewünschte Versionsnummer und stellen die Versionsvergleichsemantik bereit (d. a. Die Version muss exakt übereinstimmen, oder die Version darf nicht kleiner als der angegebene Wert sein). |
| lpszComment | Wird für Abfragen ignoriert. |
|
dwNameSpace-
Weitere Informationen finden Sie im folgenden Hinweis. |
Bezeichner eines einzelnen Namespaces, in dem die Suche eingeschränkt werden soll, oder NS_ALL 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 Ausgangspunkt der Abfrage in einem hierarchischen Namespace an. |
| dwNumberOfProtocols | Die Größe des Protokolleinschränkungsarrays kann null sein. |
| lpafpProtocols | (Optional) Verweist auf ein Array AFPROTOCOLS Struktur. Nur Dienste, die diese Protokolle verwenden, werden zurückgegeben. |
| lpszQueryString- | (Optional) Einige Namespaces (z. B. whois++) unterstützen erweiterte 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) Dies ist ein Zeiger auf eine anbieterspezifische Entität. |
Windows 8.1 und Windows Server 2012 R2-: Die WSALookupServiceBeginW--Funktion wird für Windows Store-Apps unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.
Anmerkung
Der winsock2.h-Header definiert WSALookupServiceBegin als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 8.1, Windows Vista [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | winsock2.h |
| Library | Ws2_32.lib |
| DLL- | Ws2_32.dll |
Siehe auch
Bluetooth- und WSALookupServiceBegin-