LPNSPV2LOOKUPSERVICENEXTEX Rückruffunktion (ws2spi.h)

Artikel
07/16/2024

Die NSPv2LookupServiceNextEx--Funktion wird aufgerufen, nachdem ein Handle aus einem vorherigen Aufruf von NSPv2LookupServiceBegin abgerufen wurde, um die angeforderten Informationen aus einem Namespace version-2-Dienstanbieter abzurufen.

Syntax

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

Parameter

[in] hAsyncCall

Ein Handle, das vom vorherigen Aufruf an NSPv2LookupServiceBegin für asynchrone Aufrufe zurückgegeben wird.

[in] hLookup

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

[in] dwControlFlags

Die Flags, die zum Steuern des nächsten Vorgangs verwendet werden. Derzeit wird nur LUP_FLUSHPREVIOUS als Mittel zum Behandeln eines zu großen Resultsets definiert. Wenn eine Anwendung keinen ausreichend großen Puffer bereitstellen kann, weist das Festlegen LUP_FLUSHPREVIOUS den Anbieter an, den letzten Resultset zu verwerfen, der zu groß war, und zum nächsten Satz für diesen Aufruf zu wechseln.

[in, out] lpdwBufferLength

Die Größe in Bytes für die Eingabe, die im Puffer enthalten ist, auf die durch lpqsResultsverwiesen wird. Wenn die Funktion bei der Ausgabe fehlschlägt und der Fehler WSAEFAULT ist, enthält sie die Mindestgröße in Bytes, die für die lpqsResults übergeben werden, um den Datensatz abzurufen.

[out] lpqsResults

Ein Zeiger auf einen Speicherblock, der beim Zurückgeben ein Resultset in einer WSAQUERYSET2 Struktur enthält.

Rückgabewert

Die Funktion sollte NO_ERROR (Null) zurückgeben, wenn die Routine erfolgreich ist. Es sollte SOCKET_ERROR (d. h. 1) zurückgeben, wenn die Routine fehlschlägt und den entsprechenden Fehlercode mit WSASetLastError-festlegen muss.

Fehlercode	Bedeutung
WSA_E_CANCELLED	Ein Aufruf von NSPv2LookupServiceEnd wurde ausgeführt, während dieser Anruf noch verarbeitet wurde. Der Anruf wurde abgebrochen. Die Daten im lpqsResults Puffer sind nicht definiert. In Windows Sockets 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. Namespace Anbieter sollten den WSA_E_CANCELLED Fehlercode verwenden, um die Kompatibilität mit der größtmöglichen Palette von Anwendungen aufrechtzuerhalten.
WSA_E_NO_MORE	Es sind keine weiteren Daten verfügbar. In Windows Sockets 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. Namespace Anbieter sollten den WSA_E_NO_MORE Fehlercode verwenden, um die Kompatibilität mit dem größtmöglichen Anwendungsspektrum aufrechtzuerhalten.
WSAEFAULT-	Der lpqsResults- Puffer war zu klein, um einen WSAQUERYSET- Satz zu enthalten.
WSAEINVAL-	Mindestens ein Parameter ist für diesen Anbieter ungültig oder fehlt.
WSA_INVALID_HANDLE	Der angegebene Nachschlagepunkt ist ungültig.
WSANO_DATA	Der Name wurde in der Datenbank gefunden, aber es wurden keine Daten gefunden, die den angegebenen Einschränkungen entsprechen.
WSASERVICE_NOT_FOUND	Der Dienst ist unbekannt. Der Dienst wurde im angegebenen Namespace nicht gefunden.
WSA_NOT_ENOUGH_MEMORY	Es steht nicht genügend Arbeitsspeicher zur Verfügung, um diesen Vorgang auszuführen.

Bemerkungen

Die NSPv2LookupServiceNextEx--Funktion wird als Teil der namespacedienstanbieter version-2 (NSPv2)-Architektur verwendet, die unter Windows Vista und höher verfügbar ist.

Unter Windows Vista und Windows Server 2008 kann die funktion NSPv2LookupServiceNextEx nur für Vorgänge auf NS_EMAIL Namespaceanbietern verwendet werden.

Der Anbieter übergibt eine WSAQUERYSET2 Struktur im lpqsResults Puffer. Der Client sollte die funktion NSPv2LookupServiceNextEx aufrufen, bis sie WSA_E_NOMOREzurückgibt, was angibt, dass alle WSAQUERYSET2 Strukturen zurückgegeben wurden.

Die in dieser Funktion angegebenen dwControlFlags und die zum Zeitpunkt NSPv2LookupServiceBegin als "Einschränkungen" für die Kombination behandelt werden. Die Einschränkungen werden zwischen den NSPv2LookupServiceBegin Uhrzeit und den NSPv2LookupServiceNextEx Zeit kombiniert. Daher können die Flags bei NSPv2LookupServiceNextEx niemals die Menge der bei NSPv2LookupServiceBeginzurückgegebenen Daten erhöhen, obwohl es kein Fehler ist, mehr oder weniger Flags anzugeben. Die bei einem bestimmten NSPv2LookupServiceNext Ex 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 der Flags in NSPv2LookupServiceNextExverwendet wird, haben sie unabhängig von der Einstellung der gleichen Flags bei NSPv2LookupServiceBeginihren definierten Effekt.

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

Wenn LUP_RETURN_BLOB beispielsweise bei NSPv2LookupServiceBeginnicht angegeben ist, aber bei NSPv2LookupServiceNextExangegeben wird, enthalten die zurückgegebenen Informationen nicht die privaten Daten. Es wird kein Fehler generiert.

Die NSPv2LookupServiceNextEx- Funktion wird in der Regel mindestens zweimal aufgerufen. Das erste Mal, um die Größe des erforderlichen Puffers abzurufen, um die WSAQUERYSET2 zu empfangen, auf die der lpqsResults Parameter verweist, und das zweite Mal, um das tatsächliche Abfrageergebnissatz abzurufen. Beim ersten Aufruf sollte der NSPv2-Anbieter die für die WSAQUERYSET2 Ergebnisse erforderliche Größe zurückgeben.

Die WSAQUERYSET2 Struktur, auf die durch den lpqsResults Parameter verwiesen wird, der zurückgegeben wird, ist nur im gleichen Prozesskontext nützlich, da mehrere Elemente in der WSAQUERYSET2-Struktur Zeiger auf die tatsächlich zurückgegebenen Daten enthalten. Wenn das Abfrageergebnis an einen anderen Prozess übergeben werden muss (z. B. mithilfe von RPC), müssen die in der WSAQUERYSET2 Struktur zurückgegebenen Daten serialisiert und gemarstet werden, auf die durch den lpqsResults Parameter verwiesen wird, einschließlich der Daten, auf die von Elementen in der WSAQUERYSET2 Struktur verwiesen wird. Die Daten müssen in einem Formular serialisiert werden, das über Prozessgrenzen hinweg übergeben werden kann. Das Übergeben einer Kopie der WSAQUERYSET2-Struktur reicht nicht aus, da nur Zeiger auf Daten übergeben werden und die tatsächlichen Daten für andere Prozesse nicht verfügbar sind.

Abfrageergebnisse

Die folgende Tabelle enthält WSAQUERYSET2 und beschreibt, wie Abfrageergebnisse in der Struktur **WSAQUERYSET2** dargestellt werden. Weitere Informationen finden Sie unter Query-Related Datenstrukturen.

WSAQUERYSET2 Mitgliedsname	Ergebnisinterpretation
dwSize	Die Größe WSAQUERYSET2 Struktur in Byte. Dies wird als Versionsverwaltungsmechanismus verwendet.
lpszServiceInstanceName	Eine Zeichenfolge, die den Dienstnamen enthält.
lpVersion	Verweist auf die Versionsnummer der jeweiligen Dienstinstanz.
lpszComment	Eine Kommentarzeichenfolge, die von der Dienstinstanz bereitgestellt wird. Dieses Mitglied ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNameSpace	Der Namespacebezeichner, in dem der Name oder die Dienstinstanz gefunden wurde.
lpNSProviderId	Der spezifische Namespaceanbieter, der dieses Abfrageergebnis bereitgestellt hat.
lpszContext	Der Kontextpunkt in einem hierarchischen Namespace, an dem sich der Dienst befindet.
dwNumberOfProtocols	Dieses Element ist für Ergebnisse nicht definiert.
lpafpProtocols	Dieses Element ist für Ergebnisse nicht definiert. Alle erforderlichen Protokollinformationen sind in den CSADDR_INFO Strukturen enthalten.
lpszQueryString	Wenn dwControlFlags- LUP_RETURN_QUERY_STRING enthält, gibt dieses Element 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 lpszServiceInstanceName vollständig analysiert und LUP_RETURN_QUERY_STRING verwendet wird, ist dieses Element NULL oder verweist auf eine leere Zeichenfolge.
dwNumberOfCsAddrs	Die Anzahl der Elemente im Array von CSADDR_INFO Strukturen.
lpcsaBuffer	Ein Zeiger auf ein Array von CSADDR_INFO Strukturen mit einer vollständigen Transportadresse, die in jedem Element enthalten ist.
dwOutputFlags	Das Flag RESULT_IS_ALIAS gibt an, dass es sich um ein Aliasergebnis handelt.
lpBlob	Ein Zeiger auf eine anbieterspezifische Entität. Dieses Mitglied ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	ws2spi.h

Siehe auch

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup-

NSPv2ClientSessionRundown-

NSPv2LookupServiceBegin-

NSPv2LookupServiceEnd-

WSAQUERYSET2 Mitgliedsname	Ergebnisinterpretation
dwSize	Die Größe WSAQUERYSET2 Struktur in Byte. Dies wird als Versionsverwaltungsmechanismus verwendet.
lpszServiceInstanceName	Eine Zeichenfolge, die den Dienstnamen enthält.
lpVersion	Verweist auf die Versionsnummer der jeweiligen Dienstinstanz.
lpszComment	Eine Kommentarzeichenfolge, die von der Dienstinstanz bereitgestellt wird. Dieses Mitglied ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.
dwNameSpace	Der Namespacebezeichner, in dem der Name oder die Dienstinstanz gefunden wurde.
lpNSProviderId	Der spezifische Namespaceanbieter, der dieses Abfrageergebnis bereitgestellt hat.
lpszContext	Der Kontextpunkt in einem hierarchischen Namespace, an dem sich der Dienst befindet.
dwNumberOfProtocols	Dieses Element ist für Ergebnisse nicht definiert.
lpafpProtocols	Dieses Element ist für Ergebnisse nicht definiert. Alle erforderlichen Protokollinformationen sind in den CSADDR_INFO Strukturen enthalten.
lpszQueryString	Wenn dwControlFlags- LUP_RETURN_QUERY_STRING enthält, gibt dieses Element 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 lpszServiceInstanceName vollständig analysiert und LUP_RETURN_QUERY_STRING verwendet wird, ist dieses Element NULL oder verweist auf eine leere Zeichenfolge.
dwNumberOfCsAddrs	Die Anzahl der Elemente im Array von CSADDR_INFO Strukturen.
lpcsaBuffer	Ein Zeiger auf ein Array von CSADDR_INFO Strukturen mit einer vollständigen Transportadresse, die in jedem Element enthalten ist.
dwOutputFlags	Das Flag RESULT_IS_ALIAS gibt an, dass es sich um ein Aliasergebnis handelt.
lpBlob	Ein Zeiger auf eine anbieterspezifische Entität. Dieses Mitglied ist optional, abhängig von den Anforderungen des NSPv2-Dienstanbieters.

Freigeben über