LPNSPIOCTL-Rückruffunktion (ws2spi.h)
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 |
|---|---|
|
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 |
|---|---|
| Der hLookup-Parameter war kein gültiges Abfragehandle, das von NSPLookupServiceBegin zurückgegeben wurde. | |
| Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt. | |
| 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. | |
| 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. | |
| Fehler beim Netzwerksubsystem. | |
| 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. | |
|
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:
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.
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 |