WSAIoctl-Funktion (winsock2.h)

Artikel
03/06/2024

Die WSAIoctl-Funktion steuert den Modus eines Sockets.

Syntax

int WSAAPI WSAIoctl(
  [in]  SOCKET                             s,
  [in]  DWORD                              dwIoControlCode,
  [in]  LPVOID                             lpvInBuffer,
  [in]  DWORD                              cbInBuffer,
  [out] LPVOID                             lpvOutBuffer,
  [in]  DWORD                              cbOutBuffer,
  [out] LPDWORD                            lpcbBytesReturned,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameter

[in] s

Ein Deskriptor, der einen Socket identifiziert.

[in] dwIoControlCode

Der Steuerungscode des auszuführenden Vorgangs. Weitere Informationen finden Sie unter Winsock IOCTLs.

[in] lpvInBuffer

Ein Zeiger auf den Eingabepuffer.

[in] 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 tatsächliche Anzahl von Bytes der Ausgabe.

[in] lpOverlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur (wird für nicht überlappende Sockets ignoriert).

[in] lpCompletionRoutine

Typ: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Hinweis Ein Zeiger auf die Abschlussroutine, die aufgerufen wird, wenn der Vorgang abgeschlossen wurde (bei nicht überlappenden Sockets ignoriert). Siehe Hinweise.

Rückgabewert

Nach erfolgreichem Abschluss gibt WSAIoctl null zurück. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAEFAULT	Der Parameter lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped oder lpCompletionRoutine ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten, oder der cbInBuffer - oder cbOutBuffer-Parameter ist zu klein.
WSAEINVAL	Der dwIoControlCode-Parameter ist kein gültiger Befehl, oder ein angegebener Eingabeparameter ist nicht akzeptabel, oder der Befehl gilt nicht für den angegebenen Sockettyp.
WSAEINPROGRESS	Die Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird.
WSAENOTSOCK	Der Deskriptor s ist kein Socket.
WSAEOPNOTSUPP	Der angegebene IOCTL-Befehl kann nicht realisiert werden. (Beispielsweise können die in SIO_SET_QOS oder SIO_SET_GROUP_QOS angegebenen FLOWSPEC-Strukturen nicht erfüllt werden.)
WSAEWOULDBLOCK	Der Socket ist als nicht blockierend gekennzeichnet, und der angeforderte Vorgang würde blockiert.
WSAENOPROTOOPT	Die Socketoption wird im angegebenen Protokoll nicht unterstützt. Beispielsweise wurde versucht, die SIO_GET_BROADCAST_ADDRESS IOCTL für einen IPv6-Socket zu verwenden, oder es wurde versucht, die TCP-SIO_KEEPALIVE_VALS IOCTL für einen Datagrammsocket zu verwenden.

Hinweise

Die WSAIoctl-Funktion wird verwendet, um Betriebsparameter festzulegen oder abzurufen, die dem Socket, dem Transportprotokoll oder dem Kommunikationssubsystem zugeordnet sind.

Wenn sowohl lpOverlapped als auch lpCompletionRoutineNULL sind, wird der Socket in dieser Funktion als nicht überlappender Socket behandelt. Bei einem nicht überlappenden Socket werden die Parameter lpOverlapped und lpCompletionRoutine ignoriert. Dies bewirkt, dass sich die Funktion wie die Ioctlsocket-Standardfunktion verhält, mit der Ausnahme, dass die Funktion blockiert werden kann, wenn sich Sockets im Blockierungsmodus befinden. Wenn socket s sich im nicht blockierenden Modus befindet, kann diese Funktion WSAEWOULDBLOCK zurückgeben, wenn der angegebene Vorgang nicht sofort abgeschlossen werden kann. In diesem Fall kann die Anwendung den Socket in den Blockiermodus ändern und die Anforderung erneut ausführen oder auf das entsprechende Netzwerkereignis warten (z. B. FD_ROUTING_INTERFACE_CHANGE oder FD_ADDRESS_LIST_CHANGE im Fall von SIO_ROUTING_INTERFACE_CHANGE oder SIO_ADDRESS_LIST_CHANGE), indem sie eine Windows-Meldung (mit WSAAsyncSelect) oder einen ereignisbasierten Benachrichtigungsmechanismus (mit WSAEventSelect) verwendet.

Bei überlappenden Sockets werden Vorgänge initiiert, die nicht sofort abgeschlossen werden können, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt. Der DWORD-Wert , auf den der zurückgegebene parameter lpcbBytesReturned verweist, kann ignoriert werden. Der endgültige Abschluss status und zurückgegebenen Bytes können abgerufen werden, wenn die entsprechende Vervollständigungsmethode signalisiert wird, wenn der Vorgang abgeschlossen ist.

Jede IOCTL kann je nach Implementierung des Dienstanbieters unbegrenzt blockiert werden. Wenn die Anwendung die Blockierung in einem WSAIoctl-Aufruf nicht tolerieren kann, werden überlappende E/A-Vorgänge für IOCTLs empfohlen, die besonders wahrscheinlich blockiert werden, einschließlich:

SIO_ADDRESS_LIST_CHANGE

SIO_FINDROUTE

SIO_FLUSH

SIO_GET_QOS

SIO_GET_GROUP_QOS

SIO_ROUTING_INTERFACE_CHANGE

SIO_SET_QOS

SIO_SET_GROUP_QOS

Einige protokollspezifische IOCTLs können auch besonders wahrscheinlich blockieren. Alle verfügbaren Informationen finden Sie im entsprechenden protokollspezifischen Anhang.

Der Prototyp für die Vervollständigungsroutine, auf die der lpCompletionRoutine-Parameter verweist, lautet wie folgt:

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")


void CALLBACK CompletionRoutine (
  IN DWORD dwError,
  IN DWORD cbTransferred,
  IN LPWSAOVERLAPPED lpOverlapped,
  IN DWORD dwFlags 
);

Die CompletionRoutine ist ein Platzhalter für einen von der Anwendung bereitgestellten Funktionsnamen. Der dwError-Parameter gibt den Abschluss status für den überlappenden Vorgang an, wie durch den lpOverlapped-Parameter angegeben. Der cbTransferred-Parameter gibt die Anzahl der empfangenen Bytes an. Der dwFlags-Parameter wird für diese IOCTL nicht verwendet. Die Vervollständigungsroutine gibt keinen Wert zurück.

Es ist möglich, ein Codierungsschema zu übernehmen, das die derzeit definierten ioctlsocket-Opcodes beibewahrt und gleichzeitig eine bequeme Möglichkeit zum Partitionieren des Opcode-Bezeichnerbereichs in so weit bietet, wie der dwIoControlCode-Parameter jetzt eine 32-Bit-Entität ist. Der dwIoControlCode-Parameter wurde so entwickelt, dass beim Hinzufügen neuer Steuercodes Protokoll- und Herstellerunabhängigkeit gewährleistet wird, während die Abwärtskompatibilität mit den Windows Sockets 1.1- und Unix-Steuercodes beibehalten wird. Der dwIoControlCode-Parameter weist die folgende Form auf.

I	O	V	T	Anbieter/Adressfamilie	Code
3	3	2	2 2	2 2 2 2 2 2 2 1 1 1 1	1 1 1 1 1 1
1	0	9	8 7	6 5 4 3 2 1 0 9 8 7 6	5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

Hinweis Die in der Tabelle angezeigten Bits im dwIoControlCode-Parameter müssen vertikal von oben nach unten nach Spalte gelesen werden. Das bit links ist also Bit 31, das nächste Bit ist Bit 30, und das ganz rechtsste Bit ist Bit 0.

Ich wird festgelegt, wenn der Eingabepuffer für den Code gültig ist, wie bei IOC_IN.

O wird festgelegt, wenn der Ausgabepuffer für den Code gültig ist, wie bei IOC_OUT. Steuerungscodes mit Eingabe- und Ausgabepuffern, die sowohl E als auch O festlegen.

V wird festgelegt, wenn keine Parameter für den Code vorhanden sind, wie bei IOC_VOID.

T ist eine 2-Bit-Menge, die den Typ der IOCTL definiert. Die folgenden Werte werden definiert:

0 Die IOCTL ist ein Standardmäßiger Unix-IOCTL-Code, wie bei FIONREAD und FIONBIO.

1 Die IOCTL ist ein generischer Windows Sockets 2 IOCTL-Code. Neue IOCTL-Codes, die für Windows Sockets 2 definiert sind, verfügen über T == 1.

2 Das IOCTL gilt nur für eine bestimmte Adressfamilie.

3 Die IOCTL gilt nur für den Anbieter eines bestimmten Anbieters, wie bei IOC_VENDOR. Mit diesem Typ können Unternehmen eine Anbieternummer zugewiesen werden, die im Parameter Vendor/Address family angezeigt wird. Anschließend kann der Anbieter neue IOCTLs definieren, die für diesen Anbieter spezifisch sind, ohne die IOCTL bei einem Clearinghouse registrieren zu müssen, was dem Anbieter Flexibilität und Datenschutz bietet.

Anbieter/Adressfamilie Eine 11-Bit-Menge, die den Anbieter definiert, der den Code besitzt (wenn T == 3) oder die Adressfamilie enthält, für die der Code gilt (wenn T == 2). Wenn dies ein Unix-IOCTL-Code (T == 0) ist, hat dieser Parameter den gleichen Wert wie der Code unter Unix. Wenn es sich um eine generische Windows Sockets 2 IOCTL (T == 1) handelt, kann dieser Parameter als Erweiterung des Codeparameters verwendet werden, um zusätzliche Codewerte bereitzustellen.

Code Die 16-Bit-Menge, die den spezifischen IOCTL-Code für den Vorgang enthält.

Die folgenden Unix IOCTL-Codes (Befehle) werden unterstützt.

Die folgenden Windows Sockets 2-Befehle werden unterstützt.

Wenn ein überlappender Vorgang sofort abgeschlossen wird, gibt WSAIoctl den Wert 0 zurück, und der lpcbBytesReturned-Parameter wird mit der Anzahl von Bytes im Ausgabepuffer aktualisiert. Wenn der überlappende Vorgang erfolgreich initiiert wurde und später abgeschlossen wird, gibt diese Funktion SOCKET_ERROR zurück und gibt fehlercode WSA_IO_PENDING an. In diesem Fall wird lpcbBytesReturned nicht aktualisiert. Wenn der überlappende Vorgang abgeschlossen ist, wird die Datenmenge im Ausgabepuffer entweder über den cbTransferred-Parameter in der Vervollständigungsroutine (sofern angegeben) oder über den lpcbTransfer-Parameter in WSAGetOverlappedResult angegeben.

Beim Aufruf mit einem überlappenden Socket muss der lpOverlapped-Parameter für die Dauer des überlappenden Vorgangs gültig sein. Der lpOverlapped-Parameter enthält die Adresse einer WSAOVERLAPPED-Struktur .

Wenn der lpCompletionRoutine-ParameterNULL ist, wird der hEvent-Parameter von lpOverlapped signalisiert, wenn der überlappende Vorgang abgeschlossen wird, wenn er ein gültiges Ereignisobjekthandle enthält. Eine Anwendung kann WSAWaitForMultipleEvents oder WSAGetOverlappedResult verwenden, um das Ereignisobjekt zu warten oder abzufragen.

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 .

Wenn lpCompletionRoutine nicht NULL ist, wird der hEvent-Parameter ignoriert und kann von der Anwendung verwendet werden, um Kontextinformationen an die Vervollständigungsroutine zu übergeben. Ein Aufrufer, der eine nicht NULLlpCompletionRoutine übergibt und später WSAGetOverlappedResult für dieselbe überlappende E/A-Anforderung aufruft, legt den fWait-Parameter für diesen Aufruf von WSAGetOverlappedResult möglicherweise nicht auf TRUE fest. In diesem Fall ist die Verwendung des hEvent-Parameters nicht definiert, und der Versuch, auf den hEvent-Parameter zu warten, führt zu unvorhersehbaren Ergebnissen.

Der Prototyp der Vervollständigungsroutine sieht wie folgt aus:


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags 
);

Diese CompletionRoutine ist ein Platzhalter für eine anwendungsdefinierte oder bibliotheksdefinierte Funktion. Die Vervollständigungsroutine wird nur aufgerufen, wenn sich der Thread in einem warnbaren Zustand befindet. Um einen Thread in einen warnungsfähigen Zustand zu versetzen, verwenden Sie die Funktion WSAWaitForMultipleEvents, WaitForSingleObjectEx oder WaitForMultipleObjectsEx , wobei der fAlertable - oder bAlertable-Parameter auf TRUE festgelegt ist.

Der dwError-Parameter von CompletionRoutine gibt die Vervollständigung status für den überlappenden Vorgang an, wie von lpOverlapped angegeben. Der cbTransferred-Parameter gibt die Anzahl der zurückgegebenen Bytes an. Derzeit sind keine Flagwerte definiert, und dwFlags ist 0. Die CompletionRoutine-Funktion gibt keinen Wert zurück.

Das Zurückgeben von dieser Funktion ermöglicht den Aufruf einer anderen ausstehenden Vervollständigungsroutine für diesen Socket. Die Vervollständigungsroutinen können in beliebiger Reihenfolge aufgerufen werden, nicht unbedingt in der gleichen Reihenfolge, in der die überlappenden Vorgänge abgeschlossen werden.

Kompatibilität

Die IOCTL-Codes mit T == 0 sind eine Teilmenge der IOCTL-Codes, die in Berkeley-Sockets verwendet werden. Insbesondere gibt es keinen Befehl, der FIOASYNC entspricht.

Hinweis Einige IOCTL-Codes erfordern zusätzliche Headerdateien. Für die Verwendung der SIO_RCVALL IOCTL ist beispielsweise die Headerdatei Mstcpip.h erforderlich.

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher 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
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll