LPNSPIOCTL-Rückruffunktion (ws2spi.h)

Artikel
08/28/2023

Die NSPIoctl-Funktion sendet eine IOCTL an einen Namespacedienstanbieter.

Syntax

LPNSPIOCTL Lpnspioctl;

INT Lpnspioctl(
  [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,
  [in]      LPWSATHREADID lpThreadId
)
{...}

Parameter

[in] hLookup

Das Suchhandle, das von einem vorherigen Aufruf der NSPLookupServiceBegin-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 enthalten den ersten Aufruf der NSPLookupServiceBegin-Funktion zum Abrufen des hLookup-Parameters . Diese vorherigen Aufrufe können auch Aufrufe der NSPLookupServiceNext-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 enthalten den ersten Aufruf der NSPLookupServiceBegin-Funktion zum Abrufen des hLookup-Parameters . Diese vorherigen Aufrufe können auch Aufrufe der NSPLookupServiceNext-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.

[in] lpThreadId

Ein Zeiger auf eine WSATHREADID-Struktur , die vom Anbieter in einem nachfolgenden Aufruf von WPUQueueApc verwendet werden soll. Der Anbieter sollte die referenzierte WSATHREADID-Struktur (nicht den Zeiger) speichern, bis die WPUQueueApc-Funktion zurückgegeben wird.

Rückgabewert

Wenn kein Fehler auftritt und der Vorgang sofort abgeschlossen wurde, sollte die NSPIoctl-FunktionNO_ERROR (null) zurückgeben. Beachten Sie, dass in diesem Fall die Vervollständigungsroutine, sofern angegeben, bereits in die Warteschlange eingereiht wurde.

Die NSPIoctl-Funktion sollte SOCKET_ERROR (d. h. 1) zurückgeben, wenn die Routine fehlschlägt, und sie muss den entsprechenden Fehlercode mithilfe von WSASetLastError festlegen.

Der Fehlercode WSA_IO_PENDING gibt an, dass ein überlappender Vorgang erfolgreich initiiert wurde und dass der Abschluss zu einem späteren Zeitpunkt angezeigt wird. Jeder andere Fehlercode gibt an, dass kein überlappender Vorgang initiiert wurde und keine Abschlussanzeige erfolgt.

Fehlercode	BESCHREIBUNG
WSA_INVALID_HANDLE	Der hLookup-Parameter war kein gültiges Abfragehandle, das von NSPLookupServiceBegin 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	Die Ressource ist vorübergehend nicht verfügbar. 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 NSPIoctl-Funktion wird verwendet, um einen E/A-Steuerungscode an einen Namespaceanbieter zu senden, um Betriebsparameter festzulegen oder abzurufen, die einem Abfragehandle zugeordnet sind. Der hLookup-Parameter ist ein Handle für die Namespaceanbieterabfrage, die zuvor von der NSPLookupServiceBegin-Funktion zurückgegeben wurde (kein Sockethandle).

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

Wenn lpCompletionNULL ist, wird die NSPIoctl-Funktion als blockierenden Aufruf ausgeführt. Der Namespaceanbieter sollte sofort zurückgegeben und nicht blockiert werden. Jeder Namespaceanbieter ist jedoch für das Erzwingen dieses Verhaltens verantwortlich.

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

SIO_NSP_NOTIFY_CHANGE

Die Microsoft-Namespaceanbieter, die diese IOCTL unterstützen, umfassen Folgendes:

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 NSPIoctl-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 NSPIoctl-Funktion wie folgt. Rufen Sie die NSPIoctl-Funktion mit dem dwControlCode-Parameter auf SIO_NSP_NOTIFY_CHANGE ohne Abschlussroutine (der lpCompletion-Parameter ist auf NULL festgelegt) nach jedem NSPLookupServiceNext-Funktionsaufruf auf, um sicherzustellen, dass die Abfragedaten weiterhin gültig sind. Wenn die Daten ungültig werden, rufen Sie die NSPLookupServiceEnd-Funktion auf, um das Abfragehandle zu schließen. Rufen Sie die NSPLookupServiceBegin-Funktion auf, um ein neues Abfragehandle abzurufen und die Abfrage erneut zu starten.

Für Multithreadanwendungen ist eine typische Methode zur Verwendung der NSPIoctl-Funktion wie folgt. Rufen Sie die NSPIoctl-Funktion auf, wobei der dwControlCode-Parameter auf SIO_NSP_NOTIFY_CHANGE mit einer Vervollständigungsroutine nach dem ersten Aufruf der NSPLookupServiceBegin-Funktion festgelegt ist. 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 NSPLookupServiceEnd-Funktion auf, um das Abfragehandle zu schließen. Rufen Sie die Funktionen NSPLookupServiceBegin und NSPIoctl 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 weniger ressourcenintensiv, 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 NSPLookupServiceEnd-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 werden. Weitere Informationen finden Sie unter ExitThread .

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2spi.h