WSALookupServiceNextA-Funktion (winsock2.h)

Artikel
11/20/2024

Die WSALookupServiceNext-Funktion wird aufgerufen, nachdem ein Handle aus einem vorherigen Aufruf von WSALookupServiceBegin abgerufen wurde, um die angeforderten Dienstinformationen abzurufen.

Der Anbieter übergibt eine WSAQUERYSET- Struktur im lpqsResults Puffer zurück. Der Client sollte diese Funktion weiterhin aufrufen, bis sie WSA_E_NO_MORE zurückgibt, was angibt, dass alle WSAQUERYSET- zurückgegeben wurden.

Syntax

INT WSAAPI WSALookupServiceNextA(
  [in]      HANDLE         hLookup,
  [in]      DWORD          dwControlFlags,
  [in, out] LPDWORD        lpdwBufferLength,
  [out]     LPWSAQUERYSETA lpqsResults
);

Parameter

[in] hLookup

Ein Handle, das vom vorherigen Aufruf an WSALookupServiceBeginzurückgegeben wird.

[in] dwControlFlags

Eine Reihe von Flags, die den Vorgang steuern. Die werte, die im dwControlFlags Parameter an die WSALookupServiceBegin-funktion übergeben werden, bestimmen die möglichen Kriterien. Alle Werte, die im dwControlFlags Parameter an die WSALookupServiceNext Funktion übergeben werden, beschränken die Kriterien für die Dienstsuche weiter.

Derzeit wird LUP_FLUSHPREVIOUS als Mittel definiert, um mit einem zu großen Resultset fertig zu werden. Wenn eine Anwendung nicht (oder nicht) einen ausreichend großen Puffer liefert, weist das Festlegen LUP_FLUSHPREVIOUS den Anbieter an, das letzte Resultset zu verwerfen , das zu groß war, und zum nächsten Satz für diesen Aufruf zu wechseln.

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
LUP_DEEP 0x0001	Abfragen tief im Gegensatz zu der ersten Ebene.
LUP_CONTAINERS 0x0002	Gibt nur Container zurück.
LUP_NOCONTAINERS 0x0004	Container nicht zurückgeben.
LUP_NEAREST 0x0008	Gibt nach Möglichkeit Ergebnisse in der Reihenfolge des Abstands zurück. Das Entfernungsmaß ist anbieterspezifisch.
LUP_RETURN_NAME 0x0010	Ruft den Namen als lpszServiceInstanceNameab.
LUP_RETURN_TYPE 0x0020	Ruft den Typ als lpServiceClassIdab.
LUP_RETURN_VERSION 0x0040	Ruft die Version als lpVersionab.
LUP_RETURN_COMMENT 0x0080	Ruft den Kommentar als lpszCommentab.
LUP_RETURN_ADDR 0x0100	Ruft die Adressen als lpcsaBufferab.
LUP_RETURN_BLOB 0x0200	Ruft die privaten Daten als lpBlobab.
LUP_RETURN_ALIASES 0x0400	Alle verfügbaren Aliasinformationen werden in aufeinanderfolgenden Aufrufen von WSALookupServiceNextzurückgegeben, und jeder zurückgegebene Alias weist den RESULT_IS_ALIAS Flagsatz auf.
LUP_RETURN_QUERY_STRING 0x0800	Ruft die Abfragezeichenfolge ab, die für die Anforderung verwendet wird.
LUP_RETURN_ALL 0x0FF0	Eine Reihe von Flags, die alle LUP_RETURN_*-Werte abrufen.
LUP_FLUSHPREVIOUS 0x1000	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.
LUP_FLUSHCACHE 0x2000	Wenn der Anbieter Informationen zwischenspeichert, ignoriert den Cache und fragt den Namespace selbst ab.
LUP_RES_SERVICE 0x8000	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.

[in, out] lpdwBufferLength

Bei eingaben die Anzahl der im Puffer enthaltenen Bytes, auf die durch lpqsResultsverwiesen wurde. Wenn die Funktion fehlschlägt und der Fehler WSAEFAULTist, enthält sie die mindeste Anzahl von Bytes, die für die lpqsResults zum Abrufen des Datensatzes übergeben werden sollen.

[out] lpqsResults

Ein Zeiger auf einen Speicherblock, der ein Resultset in einer WSAQUERYSET- Struktur für die Rückgabe enthält.

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
WSA_E_CANCELLED	Ein Aufruf von WSALookupServiceEnd wurde ausgeführt, während dieser Aufruf noch verarbeitet wurde. Der Anruf wurde abgebrochen. Die Daten im lpqsResults Puffer sind nicht definiert. In Windows Sockets, Version 2, werden widersprüchliche Fehlercodes für WSAECANCELLED- (10103) und WSA_E_CANCELLED (10111) definiert. Der Fehlercode WSAECANCELLED wird in einer zukünftigen Version entfernt, und nur WSA_E_CANCELLED bleiben erhalten. Für Windows Sockets, Version 2, sollten Anwendungen jedoch sowohl auf WSAECANCELLED als auch auf WSA_E_CANCELLED auf die größtmögliche Kompatibilität mit Namespaceanbietern prüfen, die eines verwenden.
WSA_E_NO_MORE	Es sind keine weiteren Daten verfügbar. In Windows Sockets, Version 2, werden widersprüchliche Fehlercodes für WSAENOMORE (10102) und WSA_E_NO_MORE (10110) definiert. Der Fehlercode WSAENOMORE wird in einer zukünftigen Version entfernt, und nur WSA_E_NO_MORE bleiben erhalten. Für Windows Sockets, Version 2, sollten Anwendungen jedoch sowohl auf WSAENOMORE als auch auf WSA_E_NO_MORE auf die größtmögliche Kompatibilität mit Namensraumanbietern prüfen, die eines verwenden.
WSAEFAULT-	Der lpqsResults- Puffer war zu klein, um einen WSAQUERYSET- Satz zu enthalten.
WSAEINVAL-	Mindestens ein erforderlicher Parameter war ungültig oder fehlte.
WSA_INVALID_HANDLE	Das angegebene Nachschlagekästchen ist ungültig.
WSANOTINITIALISIERT	Die WS2_32.DLL wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup- aufrufen, bevor Sie Windows Sockets-Funktionen aufrufen.
WSANO_DATA	Der Name wurde in der Datenbank gefunden, aber es wurden keine Daten gefunden, die den angegebenen Einschränkungen entsprechen.
WSA_NOT_ENOUGH_MEMORY	Zum Ausführen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden.

Bemerkungen

Der in dieser Funktion angegebene dwControlFlags Parameter und die zum Zeitpunkt der WSALookupServiceBegin angegebenen Parameter werden als Einschränkungen für die Kombination behandelt. Die Einschränkungen werden zwischen den WSALookupServiceBegin Zeit und den WSALookupServiceNext Zeit kombiniert. Daher können die Flags bei WSALookupServiceNext niemals die Menge der bei WSALookupServiceBeginzurückgegebenen Datenmenge erhöhen, obwohl es kein Fehler ist, mehr oder weniger Flags anzugeben. Die bei einem bestimmten WSALookupServiceNext angegebenen Flags gelten nur für diesen Aufruf.

Die dwControlFlags LUP_FLUSHPREVIOUS und LUP_RES_SERVICE sind Ausnahmen von der kombinierten Einschränkungsregel (da sie Verhaltenskennzeichnungen anstelle von Einschränkungskennzeichnungen sind). Wenn eines dieser Flags in WSALookupServiceNext verwendet wird, haben sie unabhängig von der Einstellung der gleichen Flags bei WSALookupServiceBeginihre definierte Wirkung.

Wenn z. B. LUP_RETURN_VERSION bei WSALookupServiceBegin angegeben wird, ruft der Dienstanbieter Datensätze einschließlich der Version ab. Wenn LUP_RETURN_VERSION bei WSALookupServiceNextNICHT angegeben ist, enthält die zurückgegebenen Informationen nicht die Version, obwohl sie verfügbar war. Es wird kein Fehler generiert.

Wenn z. B. LUP_RETURN_BLOB bei WSALookupServiceBegin nicht angegeben ist, aber bei WSALookupServiceNextangegeben wird, enthalten die zurückgegebenen Informationen nicht die privaten Daten. Es wird kein Fehler generiert.

Wenn die WSALookupServiceNext--Funktion mit einem Fehler von WSAEFAULTfehlschlägt, gibt dies an, dass der Puffer, auf den der lpqsResults Parameter verweist, zu klein war, um die Abfrageergebnisse zu enthalten. Ein neuer Puffer für eine WSAQUERYSET- sollte mit einer Größe bereitgestellt werden, die durch den Wert angegeben wird, auf den der lpdwBufferLength-Parameter verweist. Dieser neue Puffer für die WSAQUERYSET- muss einige Der Member der WSAQUERYSET- angegeben haben, bevor die WSALookupServiceNext-funktion erneut aufgerufen wird. Mindestens muss die dwSize Member des WSAQUERYSET- auf die neue Größe des Puffers festgelegt werden.

Abfrageergebnisse

In der folgenden Tabelle wird beschrieben, wie die Abfrageergebnisse in der WSAQUERYSET- Struktur dargestellt werden.

WSAQUERYSET-Mitglied	Ergebnisinterpretation
dwSize-	Wird auf sizeof( WSAQUERYSET) festgelegt. Dies wird als Versionsverwaltungsmechanismus verwendet.
dwOutputFlags	RESULT_IS_ALIAS Flag gibt an, dass es sich um ein Aliasergebnis handelt.
lpszServiceInstanceName	Referenzierte Zeichenfolge enthält den Dienstnamen.
lpServiceClassId-	Die GUID, die der Dienstklasse entspricht.
lpVersion-	Verweist auf die Versionsnummer der jeweiligen Dienstinstanz.
lpszComment	Optionale Kommentarzeichenfolge, die von der Dienstinstanz angegeben wird.
dwNameSpace-	Namespace, in dem die Dienstinstanz gefunden wurde.
lpNSProviderId-	Identifiziert den spezifischen Namespaceanbieter, der dieses Abfrageergebnis bereitgestellt hat.
lpszContext	Gibt den Kontextpunkt in einem hierarchischen Namespace an, an dem sich der Dienst befindet.
dwNumberOfProtocols	Nicht definiert für Ergebnisse.
lpafpProtocols	Für Ergebnisse nicht definiert, sind alle erforderlichen Protokollinformationen in den CSADDR_INFO Strukturen enthalten.
lpszQueryString-	Wenn dwControlFlags LUP_RETURN_QUERY_STRING enthält, gibt dieser Parameter den nicht analysierten Rest des in der ursprünglichen Abfrage angegebenen lpszServiceInstanceName zurück. In einem Namespace, der Dienste anhand hierarchischer Namen identifiziert, die einen Hostnamen und einen Dateipfad innerhalb dieses Hosts angeben, kann die zurückgegebene Adresse die Hostadresse und der nicht analysierte Rest der Dateipfad sein. Wenn der lpszServiceInstanceName vollständig analysiert und LUP_RETURN_QUERY_STRING verwendet wird, wird dieser Parameter NULL- oder verweist auf eine leere Zeichenfolge.
dwNumberOfCsAddrs	Gibt die Anzahl der Elemente im Array CSADDR_INFO Strukturen an.
lpcsaBuffer	Ein Zeiger auf ein Array von CSADDR_INFO Strukturen mit einer vollständigen Transportadresse, die in jedem Element enthalten ist.
lpBlob	(Optional) Dies ist ein Zeiger auf eine anbieterspezifische Entität.

Windows Phone 8: Die WSALookupServiceNextW--Funktion wird für Windows Phone Store-Apps unter Windows Phone 8 und höher unterstützt.

Windows 8.1 und Windows Server 2012 R2: Die WSALookupServiceNextW--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 WSALookupServiceNext 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