WSAIoctl-Funktion (winsock2.h)
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
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 |
---|---|
Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt. | |
Fehler beim Netzwerksubsystem. | |
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. | |
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. | |
Die Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird. | |
Der Deskriptor s ist kein Socket. | |
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.) | |
Der Socket ist als nicht blockierend gekennzeichnet, und der angeforderte Vorgang würde blockiert. | |
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 |
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.
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.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 |
Weitere Informationen
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für