WSANSPIoctl-Funktion (winsock2.h)

Artikel
03/04/2024

Mit der WSANSPIoctl-Funktion von Windows Sockets können Entwickler E/A-Steuerungsaufrufe an einen registrierten Namespace ausführen.

Syntax

INT WSAAPI WSANSPIoctl(
  [in]      HANDLE          hLookup,
  [in]      DWORD           dwControlCode,
  [in]      LPVOID          lpvInBuffer,
  [in, out] DWORD           cbInBuffer,
  [out]     LPVOID          lpvOutBuffer,
  [in]      DWORD           cbOutBuffer,
  [out]     LPDWORD         lpcbBytesReturned,
  [in]      LPWSACOMPLETION lpCompletion
);

Parameter

[in] hLookup

Das Nachschlagehandle, das von einem vorherigen Aufruf der WSALookupServiceBegin-Funktion zurückgegeben wurde.

[in] dwControlCode

Der Steuerungscode des auszuführenden Vorgangs.

Die Werte, die für den dwControlCode-Parameter verwendet werden können, werden vom Namespaceanbieter bestimmt.

Der folgende Wert wird von mehreren Microsoft-Namespaceanbietern unterstützt, einschließlich des Namespaceanbieters network location awareness (NS_NLA). Diese IOCTL ist in der Winsock2.h-Headerdatei definiert.

Wert	Bedeutung
SIO_NSP_NOTIFY_CHANGE	Mit diesem Vorgang wird überprüft, ob die ergebnisse, die bei vorherigen Aufrufen mit dem hLookup-Parameter zurückgegeben wurden, weiterhin gültig sind. Diese vorherigen Aufrufe umfassen den ersten Aufruf der WSALookupServiceBegin-Funktion zum Abrufen des hLookup-Parameters . Diese vorherigen Aufrufe können auch Aufrufe der WSALookupServiceNext-Funktion mithilfe des hLookup-Parameters enthalten.

Wert

Bedeutung

SIO_NSP_NOTIFY_CHANGE

Mit diesem Vorgang wird überprüft, ob die ergebnisse, die bei vorherigen Aufrufen mit dem hLookup-Parameter zurückgegeben wurden, weiterhin gültig sind. Diese vorherigen Aufrufe umfassen den ersten Aufruf der WSALookupServiceBegin-Funktion zum Abrufen des hLookup-Parameters . Diese vorherigen Aufrufe können auch Aufrufe der WSALookupServiceNext-Funktion mithilfe des hLookup-Parameters enthalten.

[in] lpvInBuffer

Ein Zeiger auf den Eingabepuffer.

[in, out] cbInBuffer

Die Größe des Eingabepuffers in Bytes.

[out] lpvOutBuffer

Ein Zeiger auf den Ausgabepuffer.

[in] cbOutBuffer

Die Größe des Ausgabepuffers in Bytes.

[out] lpcbBytesReturned

Ein Zeiger auf die Anzahl der zurückgegebenen Bytes.

[in] lpCompletion

Ein Zeiger auf eine WSACOMPLETION-Struktur , die für die asynchrone Verarbeitung verwendet wird. Legen Sie lpCompletion auf NULL fest, um die blockierende (synchrone) Ausführung zu erzwingen.

Rückgabewert

Success gibt NO_ERROR zurück. Fehler gibt SOCKET_ERROR zurück, und ein bestimmter Fehlercode kann durch Aufrufen der WSAGetLastError-Funktion abgerufen werden. In der folgenden Tabelle werden die Fehlercodes beschrieben.

Fehlercode	BESCHREIBUNG
WSA_INVALID_HANDLE	Der hLookup-Parameter war kein gültiges Abfragehandle, das von WSALookupServiceBegin zurückgegeben wurde.
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt.
WSAEFAULT	Das Argument lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer oder lpCompletion ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten. Alternativ ist das Argument cbInBuffer oder cbOutBuffer zu klein, und das Argument wird geändert, um die erforderliche Zuordnungsgröße widerzuspiegeln.
WSAEINVAL	Ein bereitgestellter Parameter ist nicht akzeptabel, oder der Vorgang gibt unangemessen Ergebnisse aus mehreren Namespaces zurück, wenn er für den angegebenen Vorgang nicht sinnvoll ist.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAEOPNOTSUPP	Der Vorgang wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der Namespaceanbieter diese Funktion nicht implementiert. Dieser Fehler kann auch zurückgegeben werden, wenn der angegebene dwControlCode ein unbekannter Befehl ist.
WSAEWOULDBLOCK	Der Socket verwendet keine überlappende E/A (asynchrone Verarbeitung), aber der lpCompletion-Parameter ist nicht NULL. Dieser Fehler wird als besondere Benachrichtigung für die SIO_NSP_NOTIFY_CHANGE IOCTL verwendet, wenn der lpCompletion-ParameterNULL (eine Abfrage) ist, um anzugeben, dass ein Abfragesatz gültig bleibt.

Hinweise

Die WSANSPIoctl-Funktion wird verwendet, um Betriebsparameter festzulegen oder abzurufen, die einem Abfragehandle für einen Namespaceanbieter zugeordnet sind. Der hLookup-Parameter ist ein Handle für die Namespaceanbieterabfrage, die zuvor von der WSALookupServiceBegin-Funktion (kein Sockethandle) zurückgegeben wurde.

Jede an einen Namespaceanbieter gesendete IOCTL kann je nach Implementierung des Namespace auf unbestimmte Zeit blockiert werden. Wenn eine Anwendung keine Blockierung in einem WSANSPIoctl-Funktionsaufruf tolerieren kann, sollten überlappende E/A-Vorgänge verwendet werden, und der lpCompletion-Parameter sollte auf eine WSACOMPLETION-Struktur verweisen. Damit eine WSANSPIoctl-Funktion nonblocking aufruft und sofort zurückgibt, legen Sie den Typmember der WSACOMPLETION-Struktur auf NSP_NOTIFY_IMMEDIATELY fest.

Wenn lpCompletionNULL ist, wird die WSANSPIoctl-Funktion als blockierenden Aufruf ausgeführt. Der Namespaceanbieter sollte sofort zurückgegeben und nicht blockiert werden. Jeder Namespace ist jedoch dafür verantwortlich, dieses Verhalten zu erzwingen.

Der folgende IOCTL-Code wird von mehreren Microsoft-Namensraumanbietern unterstützt:

SIO_NSP_NOTIFY_CHANGE

Zu den Microsoft-Namespaceanbietern, die diese IOCTL unterstützen, gehören:

NS_NLA: Der NLA-Namespaceanbieter (Network Location Awareness).
NS_PNRPNAME: Der PNRP-Namespaceanbieter (Peer Name Resolution Protocol).
NS_PNRPCLOUD: Der PNRP-Cloudnamespaceanbieter (Peer Name Resolution Protocol).

Möglicherweise werden andere Nicht-Microsoft-Namespaceanbieter installiert, die diese IOCTL ebenfalls unterstützen.

Wenn der lpCompletion-ParameterNULL ist, implementiert diese IOCTL ein besonderes Verhalten. Wenn der lpCompletion-Parameter für diese IOCTL NULL ist, ist dieser Vorgang eine Abfrage und wird sofort zurückgegeben. Wenn der Abfragesatz gültig bleibt, wird WSAEWOULDBLOCK als Benachrichtigung zurückgegeben, dass der Abfragesatz gültig bleibt. Wenn sich der Abfragesatz geändert hat und ungültig ist, wird NO_ERROR zurückgegeben, was angibt, dass der Abfragesatz erfolgreich abgefragt wurde.

Wenn der lpCompletion-Parameter nicht NULL ist und auf eine WSACOMPLETION-Struktur verweist, gibt die WSANSPIoctl-FunktionWSA_IO_PENDING zurück, wenn der überlappende Vorgang erfolgreich initiiert wurde und der Abschluss zu einem späteren Zeitpunkt angezeigt wird. Die in der WSACOMPLETION-Struktur angegebene Methode wird verwendet, um die Anwendung zu benachrichtigen, wenn der Abfragesatz noch gültig ist.

Nicht alle Namensauflösungsprotokolle können dieses Feature unterstützen, weshalb dieser Funktionsaufruf möglicherweise mit WSAEOPNOTSUPP fehlschlägt. Eine Abfrage, die Daten von mehreren Anbietern enthält, kann diese IOCTL nicht aufrufen und gibt WSAEINVAL zurück.

Die Parameter lpvInBuffer, cbInBuffer, lpvOutBuffer und cbOutBuffer werden derzeit von Microsoft-Namespaceanbietern ignoriert.

Für Singlethreadanwendungen ist eine typische Methode zur Verwendung der WSANSPIoctl-Funktion wie folgt. Rufen Sie die WSANSPIoctl-Funktion mit dem dwControlCode-Parameter auf SIO_NSP_NOTIFY_CHANGE ohne Abschlussroutine (der lpCompletion-Parameter ist auf NULL festgelegt) nach jedem WSALookupServiceNext-Funktionsaufruf auf, um sicherzustellen, dass die Abfragedaten weiterhin gültig sind. Wenn die Daten ungültig werden, rufen Sie die WSALookupServiceEnd-Funktion auf, um das Abfragehandle zu schließen. Rufen Sie die WSALookupServiceBegin-Funktion auf, um ein neues Abfragehandle abzurufen und die Abfrage erneut zu starten.

Für Multithreadanwendungen ist eine typische Methode zur Verwendung der WSANSPIoctl-Funktion wie folgt. Rufen Sie die WSANSPIoctl-Funktion mit dem dwControlCode-Parameter auf SIO_NSP_NOTIFY_CHANGE mit einer Abschlussroutine nach dem ersten Aufruf der WSALookupServiceBegin-Funktion auf. Die Anwendung würde den in der Vervollständigungsroutine angegebenen Mechanismus für die Benachrichtigung verwenden, um benachrichtigt zu werden, wenn Daten nicht mehr gültig sind. Ein gängiger Mechanismus besteht darin, ein in der Vervollständigungsroutine angegebenes Ereignis zu verwenden. Wenn die Daten ungültig werden, rufen Sie die WSALookupServiceEnd-Funktion auf, um das Abfragehandle zu schließen. Rufen Sie die Funktionen WSALookupServiceBegin und WSANSPIoctl auf, um ein neues Abfragehandle abzurufen und die Abfrage erneut zu starten.

Einige Protokolle können die Informationen einfach lokal zwischenspeichern und nach einiger Zeit ungültig machen. In diesem Fall kann eine Benachrichtigung ausgegeben werden, um anzugeben, dass der lokale Cache ungültig wurde.

Bei Namensauflösungsprotokollen mit seltenen Änderungen kann ein Namespaceanbieter ein globales Änderungsereignis angeben, das möglicherweise nicht für die Abfrage gilt, für die änderungsbenachrichtigung angefordert und ausgegeben wurde.

Sofortige Abrufvorgänge sind in der Regel viel kostengünstiger, da sie kein Benachrichtigungsobjekt erfordern. In den meisten Fällen wird dies als einfache boolesche Variablenüberprüfung implementiert. Die asynchrone Benachrichtigung kann jedoch abhängig von der Implementierung des Namespaceanbieterdiensts die Erstellung dedizierter Workerthreads und/oder prozessübergreifender Kommunikationskanäle erfordern. Außerdem entsteht ein Verarbeitungsaufwand im Zusammenhang mit dem Benachrichtigungsobjekt, das an der Signalisierung des Änderungsereignisses beteiligt ist.

Um eine asynchrone Benachrichtigungsanforderung abzubrechen, beenden Sie die ursprüngliche Abfrage mit einem WSALookupServiceEnd-Funktionsaufruf für das betroffene Abfragehandle. Wenn Sie die asynchrone Benachrichtigung für LUP_NOTIFY_HWND abbrechen, werden keine Nachrichten gesendet, es wird jedoch ein überlappender Vorgang abgeschlossen, und die Benachrichtigung wird mit dem Fehler WSA_OPERATION_ABORTED.

Hinweis Alle von einem bestimmten Thread initiierten E/A-Vorgänge werden abgebrochen, wenn dieser Thread beendet wird. Bei überlappenden Sockets können ausstehende asynchrone Vorgänge fehlschlagen, wenn der Thread geschlossen wird, bevor die Vorgänge abgeschlossen sind. Weitere Informationen finden Sie unter ExitThread .

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

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