WSAIoctl-Funktion (winsock2.h)

Artikel
07/16/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 auszuführende Steuerungscode. Siehe 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 der Bytes der Ausgabe.

[in] lpOverlapped

Ein Zeiger auf eine WSAOVERLAPPED--Struktur (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 (für nicht überlappende Sockets ignoriert). Siehe Anmerkungen.

Rückgabewert

Nach erfolgreichem Abschluss gibt die WSAIoctl- Null zurück. Andernfalls wird ein Wert von SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen WSAGetLastErrorabgerufen werden.

Fehlercode	Bedeutung
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angegeben.
WSAENETDOWN-	Fehler des Netzwerksubsystems.
WSAEFAULT-	Der lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlappedoder lpCompletionRoutine Parameter ist nicht vollständig in einem gültigen Teil des Benutzeradressbereichs 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. (Die in SIO_SET_QOS oder SIO_SET_GROUP_QOS angegebenen FLOWSPEC-Strukturen können z. B. nicht erfüllt werden.)
WSAEWOULDBLOCK	Der Socket ist als nicht blockierend gekennzeichnet, und der angeforderte Vorgang würde blockiert.
WSAENOPROTOOPT	Die Socketoption wird für das angegebene Protokoll nicht unterstützt. Beispielsweise wurde versucht, das SIO_GET_BROADCAST_ADDRESS IOCTL auf einem IPv6-Socket zu verwenden, oder es wurde versucht, das TCP-SIO_KEEPALIVE_VALS IOCTL in einem Datagrammsocket zu verwenden.

Bemerkungen

Die WSAIoctl--Funktion wird zum Festlegen oder Abrufen von Betriebsparametern verwendet, 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 lpOverlapped- und lpCompletionRoutine Parameter ignoriert, was bewirkt, dass sich die Funktion wie die Standardfunktion ioctlsocket-Funktion verhält, außer dass die Funktion blockieren kann, wenn socket s sich im Blockierungsmodus befindet. Wenn sich socket s im nicht blockierenden Modus befindet, kann diese Funktion WSAEWOULDBLOCK zurückgeben, wenn der angegebene Vorgang nicht sofort beendet werden kann. In diesem Fall kann die Anwendung den Socket in den Blockierungsmodus ändern und die Anforderung erneut auffordern 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) mithilfe einer Windows-Nachricht (unter Verwendung von WSAAsyncSelect)-basierten Ereignis oder Ereignis (mit WSAEventSelect)-basierten Benachrichtigungsmechanismus.

Bei überlappenden Sockets werden Vorgänge, die nicht sofort abgeschlossen werden können, initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angegeben. Der von der lpcbBytesReturned zurückgegebene Parameter DWORD--Wert kann ignoriert werden. Der endgültige Abschlussstatus und die zurückgegebenen Bytes können abgerufen werden, wenn die entsprechende Abschlussmethode signalisiert wird, wenn der Vorgang abgeschlossen ist.

Jede IOCTL kann je nach Implementierung des Dienstanbieters unbegrenzt blockiert werden. Wenn die Anwendung das Blockieren in einem WSAIoctl Aufruf nicht tolerieren kann, wird überlappende E/A für IOCTLs empfohlen, die besonders wahrscheinlich blockieren, 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 blockiert werden. Überprüfen Sie den entsprechenden protokollspezifischen Anhang auf alle verfügbaren Informationen.

Der Prototyp für die Vervollständigungsroutine, auf die die 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 vom Anwendung bereitgestellten Funktionsnamen. Der parameter dwError gibt den Abschlussstatus für den überlappenden Vorgang an, wie durch lpOverlapped Parameter angegeben. Der cbTransferred Parameter gibt die Anzahl der empfangenen Bytes an. Der dwFlags Parameter wird für diese IOCTL nicht verwendet. Die Abschlussroutine gibt keinen Wert zurück.

Es ist möglich, ein Codierungsschema zu übernehmen, das das derzeit definierte ioctlsocket opcodes beibehalten und gleichzeitig eine bequeme Möglichkeit bietet, den Opcode-Bezeichnerbereich so weit zu partitionieren, wie der dwIoControlCode- Parameter jetzt eine 32-Bit-Entität ist. Der dwIoControlCode Parameter ist so aufgebaut, dass die Protokoll- und Herstellerunabhängigkeit beim Hinzufügen neuer Steuercodes ermöglicht und gleichzeitig die Abwärtskompatibilität mit den Windows Sockets 1.1- und Unix-Steuerelementcodes beibehalten wird. Der dwIoControlCode Parameter hat das folgende Formular.

Ich	O	V	T	Hersteller/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

Note The bits in dwIoControlCode parameter displayed in the table must be read vertically from top to bottom by column. Das linksste Bit ist also Bit 31, das nächste Bit ist Bit 30, und das bit am weitesten rechts ist Bit 0.

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

O wird festgelegt, wenn der Ausgabepuffer wie bei IOC_OUTfür den Code gültig ist. Steuercodes, die sowohl Eingabe- als auch Ausgabepuffer verwenden, legen I und O fest.

V ist festgelegt, wenn es keine Parameter für den Code gibt, wie bei IOC_VOID.

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

0 Die IOCTL ist ein Unix IOCTL-Standardcode, wie bei FIONREAD und FIONBIO.

1 IOCTL ist ein generischer IOCTL-Code für Windows Sockets 2. Neue für Windows Sockets 2 definierte IOCTL-Codes verfügen über T == 1.

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

3 Das IOCTL gilt nur für den Anbieter eines bestimmten Anbieters, wie bei IOC_VENDOR. Mit diesem Typ können Unternehmen eine Lieferantennummer zugewiesen werden, die im parameter Vendor/Address Family angezeigt wird. Anschließend kann der Anbieter neue IOCTLs für diesen Anbieter definieren, ohne das IOCTL bei einem Clearinghouse registrieren zu müssen, wodurch die Flexibilität und privatsphäre des Anbieters gewährleistet ist.

Hersteller/Adressfamilie Eine 11-Bit-Menge, die den Anbieter definiert, der den Code besitzt (wenn T == 3) oder die die Adressfamilie enthält, auf die der Code angewendet wird (wenn T == 2). Wenn es sich um einen Unix IOCTL-Code (T == 0) handelt, hat dieser Parameter den gleichen Wert wie der Code auf 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 einen Wert von Null zurück, und der lpcbBytesReturned Parameter wird mit der Anzahl der Bytes im Ausgabepuffer aktualisiert. Wenn der überlappende Vorgang erfolgreich initiiert und später abgeschlossen wird, gibt diese Funktion SOCKET_ERROR zurück und gibt fehlercode WSA_IO_PENDINGan. In diesem Fall wird lpcbBytesReturned nicht aktualisiert. Wenn der überlappende Vorgang die Datenmenge im Ausgabepuffer abgeschlossen hat, wird entweder über den cbTransferred Parameter in der Abschlussroutine (sofern angegeben) oder über den lpcbTransfer Parameter in WSAGetOverlappedResultangegeben.

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

Wenn der lpCompletionRoutine Parameter NULL-ist, wird der hEvent Parameter lpOverlapped signalisiert, wenn der überlappende Vorgang abgeschlossen ist, 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 sind. 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 Abschlussroutine zu übergeben. Ein Aufrufer, der eine nichtNULL-lpCompletionRoutine- und später aufruft, WSAGetOverlappedResult- für dieselbe überlappende E/A-Anforderung nicht den fWait Parameter für diesen Aufruf von WSAGetOverlappedResult- auf TRUEfestlegen. In diesem Fall ist die Verwendung des hEvent--Parameters nicht definiert, und der Versuch, auf den hEvent Parameter zu warten, würde zu unvorhersehbaren Ergebnissen führen.

Der Prototyp der Abschlussroutine lautet wie folgt:


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 Abschlussroutine wird nur aufgerufen, wenn sich der Thread in einem warnungsfähigen Zustand befindet. Um einen Thread in einen warnbaren Zustand zu versetzen, verwenden Sie die WSAWaitForMultipleEvents, WaitForSingleObjectExoder WaitForMultipleObjectsEx Funktion mit der fAlertable oder bAlertable Parameter auf TRUEfestgelegt ist.

Der dwError Parameter von CompletionRoutine gibt den Abschlussstatus für den überlappenden Vorgang an, wie durch lpOverlappedangegeben. Der parameter cbTransferred gibt die Anzahl der zurückgegebenen Bytes an. Derzeit werden keine Flagwerte definiert, und dwFlags- null ist. Die CompletionRoutine--Funktion gibt keinen Wert zurück.

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

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. Die Verwendung der SIO_RCVALL IOCTL erfordert beispielsweise die Mstcpip.h-Headerdatei.

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 unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winsock2.h
Library	Ws2_32.lib
DLL-	Ws2_32.dll