WSAIoctl, fonction (winsock2.h)
La fonction WSAIoctl contrôle le mode d’un socket.
Syntaxe
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
);
Paramètres
[in] s
Descripteur identifiant un socket.
[in] dwIoControlCode
Code de contrôle de l’opération à effectuer. Voir Winsock IOCTLs.
[in] lpvInBuffer
Pointeur vers la mémoire tampon d’entrée.
[in] cbInBuffer
Taille, en octets, de la mémoire tampon d’entrée.
[out] lpvOutBuffer
Pointeur vers la mémoire tampon de sortie.
[in] cbOutBuffer
Taille, en octets, de la mémoire tampon de sortie.
[out] lpcbBytesReturned
Pointeur vers le nombre réel d’octets de sortie.
[in] lpOverlapped
Pointeur vers une structure WSAOVERLAPPED
[in] lpCompletionRoutine
Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Valeur de retour
Une fois l’achèvement réussi, le WSAIoctl
| Code d’erreur | Signification |
|---|---|
| Une opération superposée a été lancée et l’achèvement sera indiqué ultérieurement. | |
| Le sous-système réseau a échoué. | |
| Le lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped, ou paramètre lpCompletionRoutineRoutine n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur, ou le paramètre cbInBuffer ou cbOutBuffer est trop petit. | |
| Le paramètre dwIoControlCode n’est pas une commande valide, ou un paramètre d’entrée spécifié n’est pas acceptable, ou la commande n’est pas applicable au type de socket spécifié. | |
| La fonction est appelée lorsqu’un rappel est en cours. | |
| Le descripteur n’est pas un socket. | |
| Impossible de réaliser la commande IOCTL spécifiée. (Par exemple, les structures FLOWSPEC spécifiées dans SIO_SET_QOS ou SIO_SET_GROUP_QOS ne peuvent pas être satisfaites.) | |
| Le socket est marqué comme non bloquant et l’opération demandée bloquerait. | |
| L’option de socket n’est pas prise en charge sur le protocole spécifié. Par exemple, une tentative d’utilisation de la SIO_GET_BROADCAST_ADDRESS IOCTL a été effectuée sur un socket IPv6 ou une tentative d’utilisation du protocole TCP SIO_KEEPALIVE_VALS IOCTL a été effectuée sur un socket de datagramme. |
Remarques
La fonction WSAIoctl
Si les deux lpOverlapped et lpCompletionRoutine sont NULL, le socket de cette fonction sera traité comme un socket non superposé. Pour un socket non superposé, lpOverlapped et paramètres lpCompletionRoutine sont ignorés, ce qui entraîne l’abandon de la fonction comme la fonction standard ioctlsocket, sauf que la fonction peut bloquer si le socket s est en mode bloquant. Si le du socket
Pour les sockets superposés, les opérations qui ne peuvent pas être terminées immédiatement seront lancées et l’achèvement sera indiqué ultérieurement. La valeur DWORD pointée par le paramètre lpcbBytesReturned retourné peut être ignoré. L’état d’achèvement final et les octets retournés peuvent être récupérés lorsque la méthode d’achèvement appropriée est signalée lorsque l’opération est terminée.
Toute IOCTL peut bloquer indéfiniment, en fonction de l’implémentation du fournisseur de services. Si l’application ne peut pas tolérer le blocage dans un appel WSAIoctl, les E/S superposées sont recommandées pour les IOCTL qui sont particulièrement susceptibles de bloquer, notamment :
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
Certains IOCTL spécifiques au protocole peuvent également être particulièrement susceptibles de bloquer. Vérifiez l’annexe spécifique au protocole appropriée pour obtenir des informations disponibles.
Le prototype de la routine d’achèvement pointée par le paramètre lpCompletionRoutine est le suivant :
#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
);
CompletionRoutine est un espace réservé pour un nom de fonction fourni par l’application. Le paramètre dwError spécifie l’état d’achèvement de l’opération qui se chevauche, comme indiqué par paramètre lpOverlapped. Le paramètre cbTransferred spécifie le nombre d’octets reçus. Le paramètre dwFlags n’est pas utilisé pour cette IOCTL. La routine d’achèvement ne retourne pas de valeur.
Il est possible d’adopter un schéma d’encodage qui conserve les ioctlsocket actuellement définis opcodes tout en fournissant un moyen pratique de partitionner l’espace d’identificateur opcode autant que le paramètre dwIoControlCode est désormais une entité 32 bits. Le paramètre dwIoControlCode est conçu pour permettre l’indépendance du protocole et du fournisseur lors de l’ajout de nouveaux codes de contrôle tout en conservant la compatibilité descendante avec les codes de contrôle Windows Sockets 1.1 et Unix. Le paramètre dwIoControlCode a le formulaire suivant.
| Je | O | V | T | Famille de fournisseurs/adresses | 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 est défini si la mémoire tampon de sortie est valide pour le code, comme avec IOC_OUT. Les codes de contrôle utilisant des mémoires tampons d’entrée et de sortie définissent à la fois les E/S et les E/S.
V est défini s’il n’existe aucun paramètre pour le code, comme avec IOC_VOID.
T est une quantité 2 bits qui définit le type du IOCTL. Les valeurs suivantes sont définies :
0 Le IOCTL est un code IOCTL Unix standard, comme avec FIONREAD et FIONBIO.
1 Le IOCTL est un code IOCTL Windows Sockets 2 générique. Les nouveaux codes IOCTL définis pour Windows Sockets 2 auront T == 1.
2 Le IOCTL s’applique uniquement à une famille d’adresses spécifique.
3 Le IOCTL s’applique uniquement au fournisseur d’un fournisseur spécifique, comme avec IOC_VENDOR. Ce type permet aux entreprises d’attribuer un numéro de fournisseur qui apparaît dans la famille Fournisseur/Adresse paramètre. Ensuite, le fournisseur peut définir de nouveaux IOCTL spécifiques à ce fournisseur sans avoir à inscrire le IOCTL auprès d’un centre d’information, fournissant ainsi la flexibilité et la confidentialité du fournisseur.
famille Fournisseur/Adresse Quantité 11 bits qui définit le fournisseur propriétaire du code (si T == 3) ou qui contient la famille d’adresses à laquelle le code s’applique (si T == 2). S’il s’agit d’un code IOCTL Unix (T == 0), ce paramètre a la même valeur que le code sur Unix. S’il s’agit d’un IOCTL Windows Sockets 2 générique (T == 1), ce paramètre peut être utilisé comme extension du paramètre de code pour fournir des valeurs de code supplémentaires.
Code Quantité 16 bits qui contient le code IOCTL spécifique pour l’opération.
Les codes IOCTL Unix suivants (commandes) sont pris en charge.
Les commandes Windows Sockets 2 suivantes sont prises en charge.
Si une opération se chevauche immédiatement, WSAIoctl retourne la valeur zéro et le paramètre lpcbBytesReturned est mis à jour avec le nombre d’octets dans la mémoire tampon de sortie. Si l’opération qui se chevauche est lancée et se termine ultérieurement, cette fonction retourne SOCKET_ERROR et indique le code d’erreur WSA_IO_PENDING. Dans ce cas, lpcbBytesReturned n’est pas mis à jour. Lorsque l’opération superposée termine la quantité de données dans la mémoire tampon de sortie est indiquée via le paramètre cbTransferred dans la routine d’achèvement (si spécifié), ou via le paramètre lpcbTransfer dans WSAGetOverlappedResult.
Lorsqu’il est appelé avec un socket qui se chevauche, le paramètre
Si le paramètre lpCompletionRoutine est NULL, le paramètre hEvent de lpOverlapped est signalé lorsque l’opération qui se chevauche se termine si elle contient un handle d’objet d’événement valide. Une application peut utiliser WSAWaitForMultipleEvents ou WSAGetOverlappedResult attendre ou interroger l’objet d’événement.
Le prototype de la routine d’achèvement est le suivant :
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Cette CompletionRoutine est un espace réservé pour une fonction définie par l’application ou une bibliothèque. La routine d’achèvement est appelée uniquement si le thread est dans un état d’alerte. Pour placer un thread dans un état d’alerte, utilisez la fonction
Le paramètre dwError de CompletionRoutine spécifie l’état d’achèvement de l’opération qui se chevauche, comme indiqué par lpOverlapped. Le paramètre cbTransferred spécifie le nombre d’octets retournés. Actuellement, aucune valeur d’indicateur n’est définie et dwFlags sera égale à zéro. La fonction CompletionRoutine ne retourne pas de valeur.
Le retour de cette fonction permet l’appel d’une autre routine d’achèvement en attente pour ce socket. Les routines d’achèvement peuvent être appelées dans n’importe quel ordre, pas nécessairement dans le même ordre que les opérations superposées sont terminées.
compatibilité
Les codes IOCTL avec T == 0 sont un sous-ensemble des codes IOCTL utilisés dans les sockets Berkeley. En particulier, il n’existe aucune commande équivalente à FIOASYNC .windows 8.1 et Windows Server 2012 R2: cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | winsock2.h |
| bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |
Voir aussi
options de socket SOL_SOCKET