Freigeben über


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
LUP_DEEP
0x0001
Fragt tief ab und nicht nur auf der ersten Ebene.
LUP_CONTAINERS
0x0002
Gibt nur Container zurück.
LUP_NOCONTAINERS
0x0004
Geben Sie 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 WSALookupServiceNext zurückgegeben, und für jeden zurückgegebenen Alias ist das flag RESULT_IS_ALIAS festgelegt.
LUP_RETURN_QUERY_STRING
0x0800
Ruft die für die Anforderung verwendete Abfragezeichenfolge ab.
LUP_RETURN_ALL
0x0FF0
Ein Satz von Flags, der alle LUP_RETURN_*-Werte abruft.
LUP_FLUSHPREVIOUS
0x1000
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.
LUP_FLUSHCACHE
0x2000
Wenn der Anbieter Informationen zwischengespeichert hat, ignoriert den Cache und fragt den Namespace ab.
LUP_RES_SERVICE
0x8000
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
WSA_NOT_ENOUGH_MEMORY
Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang auszuführen.
WSAEINVAL
Mindestens ein Parameter fehlte oder war für diesen Anbieter ungültig.
WSANO_DATA
Der Name wurde in der Datenbank gefunden, aber es wurden keine Daten gefunden, die den angegebenen Einschränkungen entsprechen.
WSANOTINITIALISIERT
Die WS2_32.DLL wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup aufrufen, bevor Windows Sockets-Funktionen aufgerufen werden.
WSASERVICE_NOT_FOUND
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.
 
Wichtig In den meisten Fällen sollten Anwendungen, die nur an einem bestimmten Transportprotokoll interessiert sind, ihre Abfrage nach Adressfamilie und Protokoll und nicht nach Namespace einschränken. Dies würde es einer Anwendung ermöglichen, die einen TCP/IP-Dienst suchen muss, z. B. ihre Abfrage von allen verfügbaren Namespaces wie der lokalen Hostdatei, DNS und NIS verarbeiten zu lassen.
 
Windows Phone 8: Die WSALookupServiceBeginW-Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.

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

Weitere Informationen

Bluetooth und WSALookupServiceBegin

EnumProtocols

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSAEnumProtocols

WSALookupServiceEnd

WSALookupServiceNext

WSAQUERYSET

WSCEnumNameSpaceProviders32

WSCEnumNameSpaceProvidersEx32

WSCEnumProtocols

WSCEnumProtocols32