WSALookupServiceBeginA-Funktion (winsock2.h)
Die WSALookupServiceBegin-Funktion initiiert eine Clientabfrage, die durch die In einer WSAQUERYSET-Struktur enthaltenen Informationen eingeschränkt ist. WSALookupServiceBegin gibt nur ein Handle zurück, das von nachfolgenden Aufrufen von WSALookupServiceNext verwendet werden sollte, um die tatsächlichen Ergebnisse zu erhalten.
Syntax
INT WSAAPI WSALookupServiceBeginA(
[in] LPWSAQUERYSETA lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
);
Parameter
[in] lpqsRestrictions
Ein Zeiger auf die Suchkriterien. Weitere Informationen finden Sie in den Hinweisen.
[in] dwControlFlags
Eine Gruppe von Flags, die die Tiefe der Suche steuert.
Unterstützte Werte für den dwControlFlags-Parameter sind in der Winsock2.h-Headerdatei definiert und können eine Kombination der folgenden Optionen sein.
| Flag | Bedeutung |
|---|---|
|
Fragt tief ab und nicht nur auf der ersten Ebene. |
|
Gibt nur Container zurück. |
|
Geben Sie 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 WSALookupServiceNext zurückgegeben, und für jeden zurückgegebenen Alias ist das flag RESULT_IS_ALIAS festgelegt. |
|
Ruft die für die Anforderung verwendete Abfragezeichenfolge ab. |
|
Ein Satz von Flags, der alle LUP_RETURN_*-Werte abruft. |
|
Wird als Wert für den dwControlFlags-Parameter in WSALookupServiceNext verwendet. Durch Festlegen dieses Flags wird der Anbieter angewiesen, das letzte Resultset zu verwerfen, das für den angegebenen Puffer zu groß war, und mit dem nächsten Resultset fortzufahren. |
|
Wenn der Anbieter Informationen zwischengespeichert hat, ignoriert den Cache und fragt den Namespace ab. |
|
Dies gibt an, ob sich die hauptantwort im remoten oder lokalen Teil der struktur CSADDR_INFO befindet. Der andere Teil muss in beiden Fällen verwendbar sein. |
[out] lphLookup
Ein Handle, das beim Aufrufen von 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 von WSAGetLastError abgerufen werden.
| Fehlercode | Bedeutung |
|---|---|
| Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang auszuführen. | |
| Mindestens ein Parameter fehlte oder war 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 Windows Sockets-Funktionen aufgerufen werden. | |
|
Ein solcher Dienst ist nicht bekannt. Der Dienst kann nicht im angegebenen Namensraum gefunden werden.
Dieser Fehler wird für eine Bluetooth-Dienstermittlungsanforderung zurückgegeben, wenn keine Bluetooth-Remotegeräte gefunden wurden. |
Hinweise
Der parameter lpqsRestrictions 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 einschränken, indem sie die Member dwNumberOfProtocols und lpafpProtocols des WSAQUERYSET verwenden, anstatt den Namespace im dwNameSpace-Member anzugeben.
Informationen zu unterstützten Netzwerktransportprotokollen können mithilfe der Funktion EnumProtocols, WSAEnumProtocols, WSCEnumProtocols oder WSCEnumProtocols32 erneut verwendet werden.
Es ist auch möglich, die Abfrage auf einen einzelnen Namespace einzuschränken. Beispielsweise würde eine Abfrage, die nur Ergebnisse aus DNS (keine Ergebnisse aus der lokalen Hostdatei und anderen Benennungsdiensten) möchte, das dwNameSpace-Element auf NS_DNS festlegen. Beispielsweise würde eine Bluetooth-Geräteermittlung das dwNameSpace-Element 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 Funktion WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32 oder WSCEnumNameSpaceProvidersEx32 abgerufen werden.
Wenn LUP_CONTAINERS in einem Aufruf angegeben wird, sollten andere Einschränkungswerte vermieden werden. Falls angegeben, liegt es beim Namensdienstanbieter, zu entscheiden, ob er diese Einschränkung für die Container unterstützen kann. Wenn dies nicht der Fehler ist, sollte ein Fehler zurückgegeben werden.
Einige Namensdienstanbieter können über andere Möglichkeiten zum Suchen von Containern verfügen. Beispielsweise können alle Container von einem bekannten Typ oder einer Reihe bekannter Typen sein, und daher kann eine Abfrageeinschränkung erstellt werden, 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 also 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 einfach WSANO_DATA zurückgeben.
Die bevorzugte Methode zum Abrufen der Container in einem anderen Container 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 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 WSALookupServiceBegin werden die Container verwendet, die von einem vorherigen Aufruf zurückgegeben wurden.
Wie bereits erwähnt, wird eine WSAQUERYSET-Struktur als Eingabeparameter für WSALookupBegin verwendet, um die Abfrage zu qualifizieren. In der folgenden Tabelle wird angegeben, wie WSAQUERYSET zum Erstellen einer Abfrage verwendet wird. Wenn ein Parameter als (Optional) markiert ist, kann ein NULL-Zeiger angegeben werden, der angibt, dass der Parameter nicht als Suchkriterium verwendet wird. Weitere Informationen finden Sie im Abschnitt Abfragebezogene Datenstrukturen .
| WSAQUERYSET-Member | Abfrageinterpretation |
|---|---|
| dwSize | Muss auf sizeof(WSAQUERYSET) festgelegt werden. Dies ist ein Versionsverwaltungsmechanismus. |
| dwOutputFlags | Wird für Abfragen ignoriert. |
| lpszServiceInstanceName | (Optional) Die referenzierte Zeichenfolge enthält den Dienstnamen. Die Semantik für das Wildcarding innerhalb der Zeichenfolge ist nicht definiert, kann aber von bestimmten Namespaceanbietern unterstützt werden. |
| lpServiceClassId | (Erforderlich) Die GUID, die der Dienstklasse entspricht. |
| lpVersion | (Optional) Verweist auf die gewünschte Versionsnummer und stellt Versionsvergleichsemantik 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
Weitere Informationen finden Sie im folgenden Wichtigen 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 der AFPROTOCOLS-Struktur . Nur Dienste, die diese Protokolle verwenden, werden zurückgegeben. |
| lpszQueryString | (Optional) Einige Namespaces (z. B. whois++) unterstützen angereicherte 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 auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.
Hinweis
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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 8.1, Windows Vista [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winsock2.h |
| Bibliothek | Ws2_32.lib |
| DLL | Ws2_32.dll |