Fonction WSAIoctl (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 (ignoré pour les sockets non superposés).
[in] lpCompletionRoutine
Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Valeur de retour
Une fois terminé, WSAIoctl retourne zéro. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.
| Code d'erreur | Signification |
|---|---|
| Une opération qui se chevauche a été lancée avec succès et l’achèvement sera indiqué ultérieurement. | |
| Le sous-système réseau a échoué. | |
| Le paramètre lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine n’est pas entièrement 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 s 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 est bloquée. | |
| L’option socket n’est pas prise en charge sur le protocole spécifié. Par exemple, une tentative d’utilisation du 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 est utilisée pour définir ou récupérer les paramètres d’exploitation associés au socket, au protocole de transport ou au sous-système de communication.
Si lpOverlapped et lpCompletionRoutine ont la valeur NULL, le socket de cette fonction sera traité comme un socket non superposé. Pour un socket non chevauchant, les paramètres lpOverlapped et lpCompletionRoutine sont ignorés, ce qui entraîne le comportement de la fonction comme la fonction ioctlsocket standard, sauf que la fonction peut bloquer si socket s est en mode bloquant. Si le socket s est en mode non bloquant, cette fonction peut renvoyer WSAEWOULDBLOCK lorsque l’opération spécifiée ne peut pas être terminée immédiatement. Dans ce cas, l’application peut changer le socket en mode de blocage et réémettre la demande ou attendre l’événement réseau correspondant (par exemple, FD_ROUTING_INTERFACE_CHANGE ou FD_ADDRESS_LIST_CHANGE dans le cas d’SIO_ROUTING_INTERFACE_CHANGE ou de SIO_ADDRESS_LIST_CHANGE) à l’aide d’un message Windows (à l’aide de WSAAsyncSelect) ou d’un mécanisme de notification basé sur un événement (à l’aide de WSAEventSelect).
Pour les sockets qui se chevauchent, les opérations qui ne peuvent pas être effectuées immédiatement sont lancées et l’achèvement sera indiqué ultérieurement. La valeur DWORD indiquée par le paramètre lpcbBytesReturned retourné peut être ignorée. L’achèvement final status 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.
Tout 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 qui se chevauchent 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
Certaines LISTES IOCTL spécifiques au protocole peuvent également être particulièrement susceptibles de bloquer. Consultez l’annexe spécifique au protocole pertinente pour obtenir les informations disponibles.
Le prototype de la routine d’achèvement pointée vers 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 le status d’achèvement pour l’opération qui se chevauche, comme indiqué par le paramètre lpOverlapped. Le paramètre cbTransferred spécifie le nombre d’octets reçus. Le paramètre dwFlags n’est pas utilisé pour ce IOCTL. La routine d’achèvement ne retourne pas de valeur.
Il est possible d’adopter un schéma d’encodage qui conserve les opcodes ioctlsocket actuellement définis tout en offrant un moyen pratique de partitionner l’espace d’identificateur d’opcode dans la mesure où 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 la forme suivante.
| I | O | V | T | Famille fournisseur/adresse | 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 à l’aide de tampons d’entrée et de sortie définissent les E et O.
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 L’IOCTL est un code UNIX IOCTL standard, comme avec FIONREAD et FIONBIO.
1 L’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 L’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 de se voir attribuer un numéro de fournisseur qui apparaît dans le paramètre famille Fournisseur/Adresse . Ensuite, le fournisseur peut définir de nouveaux IOCTL spécifiques à ce fournisseur sans avoir à inscrire l’IOCTL auprès d’un centre d’échange, offrant ainsi flexibilité et confidentialité au fournisseur.
Famille de fournisseurs/d’adresses 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 qui se chevauche se termine immédiatement, WSAIoctl retourne une valeur de 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 correctement lancée et se terminera 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 qui se chevauche se termine, la quantité de données dans la mémoire tampon de sortie est indiquée par le biais du 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 lpOverlapped doit être valide pendant la durée de l’opération qui se chevauche. Le paramètre lpOverlapped contient l’adresse d’une structure WSAOVERLAPPED .
Si le paramètre lpCompletionRoutine a la valeur NULL, le paramètre hEvent de lpOverlapped est signalé lorsque l’opération qui se chevauche se termine s’il contient un handle d’objet d’événement valide. Une application peut utiliser WSAWaitForMultipleEvents ou WSAGetOverlappedResult pour 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
);
This CompletionRoutine est un espace réservé pour une fonction définie par l’application ou définie par la bibliothèque. La routine d’achèvement est appelée uniquement si le thread est dans un état pouvant être alerté. Pour placer un thread dans un état alerte, utilisez la fonction WSAWaitForMultipleEvents, WaitForSingleObjectEx ou WaitForMultipleObjectsEx avec le paramètre fAlertable ou bAlertable défini sur TRUE.
Le paramètre dwError de CompletionRoutine spécifie la status d’achèvement pour 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 est égal à zéro. La fonction CompletionRoutine ne retourne pas de valeur.
Le retour à partir 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 qui se chevauchent.
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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | winsock2.h |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour