code de contrôle SIO_APPLY_TRANSPORT_SETTING

Article
06/13/2023

Description

Le code de contrôle SIO_APPLY_TRANSPORT_SETTING applique un ou plusieurs paramètres de transport à un socket.

Pour effectuer cette opération, appelez la fonction WSAIoctl ou WSPIoctl avec les paramètres suivants.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Paramètres

s

Descripteur identifiant un socket.

dwIoControlCode

Code de contrôle de l’opération. Utilisez SIO_APPLY_TRANSPORT_SETTING pour cette opération.

lpvInBuffer

Pointeur vers la mémoire tampon d’entrée. Ce paramètre contient un pointeur vers une structure où le premier membre de la structure est une structure TRANSPORT_SETTING_ID qui détermine le paramètre de transport appliqué.

cbInBuffer

Taille, en octets, de la mémoire tampon d’entrée. Ce paramètre dépend du paramètre de transport appliqué.

lpvOutBuffer

Pointeur vers la mémoire tampon de sortie. Ce paramètre dépend du paramètre de transport appliqué.

cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie.

lpcbBytesReturned

Pointeur vers une variable qui reçoit la taille, en octets, des données stockées dans la mémoire tampon de sortie.

Si la mémoire tampon de sortie est trop petite, l’appel échoue, WSAGetLastError retourne WSAEINVAL et le paramètre lpcbBytesReturned pointe vers une valeur DWORD de zéro.

Si lpOverlapped a la valeur NULL, la valeur DWORD indiquée par le paramètre lpcbBytesReturned qui est retourné lors d’un appel réussi ne peut pas être égale à zéro.

Si le paramètre lpOverlapped n’est pas NULL 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 égale à zéro, car la taille des données stockées ne peut pas être déterminée tant que l’opération qui se chevauche n’est pas terminée. Le status d’achèvement final peut être récupéré lorsque la méthode d’achèvement appropriée est signalée lorsque l’opération est terminée.

lpvOverlapped

Pointeur vers une structure WSAOVERLAPPED .

Si le socket s a été créé sans l’attribut qui se chevauche, le paramètre lpOverlapped est ignoré.

Si s a été ouvert avec l’attribut qui se chevauche et que le paramètre lpOverlapped n’a pas la valeur NULL, l’opération est effectuée en tant qu’opération qui se chevauche (asynchrone). Dans ce cas, le paramètre lpOverlapped doit pointer vers une structure WSAOVERLAPPED valide.

Pour les opérations qui se chevauchent, la fonction WSAIoctl ou WSPIoctl retourne immédiatement, et la méthode d’achèvement appropriée est signalée lorsque l’opération est terminée. Sinon, la fonction ne retourne pas tant que l’opération n’est pas terminée ou qu’une erreur ne se produit pas.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération terminée (ignoré pour les sockets non superposés).

lpThreadId

Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (pas le pointeur vers le même) jusqu’à ce que la fonction WPUQueueApc soit retournée.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

lpErrno

Pointeur vers le code d’erreur.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

Valeur retournée

Si l’opération se termine correctement, la fonction WSAIoctl ou WSPIoctl retourne zéro.

Si l’opération échoue ou est en attente, la fonction WSAIoctl ou WSPIoctl retourne SOCKET_ERROR. Pour obtenir des informations d’erreur étendues, appelez WSAGetLastError.

Code d'erreur	Signification
WSA_IO_PENDING	L’opération d’E/S qui se chevauche est en cours. Cette valeur est retournée si une opération qui se chevauche a été lancée avec succès et que l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	L'opération d'E/S a été abandonnée en raison de l'arrêt d'un thread ou de la requête d'une application. Cette erreur est retournée si une opération qui se chevauche a été annulée en raison de la fermeture du socket ou de l’exécution de la commande IOCTL SIO_FLUSH .
WSAEFAULT	Le système a détecté une adresse de pointeur non valide lors de la tentative d’utilisation d’un argument pointeur dans un appel. Cette erreur est retournée du paramètre lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur.
WSAEINPROGRESS	Une opération de blocage est actuellement en cours d'exécution. Cette erreur est retournée si la fonction est appelée lorsqu’un rappel est en cours.
WSAEINTR	Une opération de blocage a été interrompue par un appel à WSACancelBlockingCall. Cette erreur est retournée si une opération de blocage a été interrompue.
WSAEINVAL	Argument non valide fourni. Cette erreur est retournée si le paramètre dwIoControlCode n’est pas une commande valide, si un paramètre d’entrée spécifié n’est pas acceptable ou si la commande n’est pas applicable au type de socket spécifié.
WSAENETDOWN	Une opération de socket a rencontré un réseau inactif. Cette erreur est retournée si le sous-système réseau a échoué.
WSAENOTSOCK	Une opération a été tentée sur un élément qui n’est pas un socket. Cette erreur est retournée si le descripteur s n’est pas un socket.
WSAEOPNOTSUPP	L’opération tentée n’est pas prise en charge pour le type d’objet référencé. Cette erreur est retournée si la commande IOCTL spécifiée n’est pas prise en charge. Cette erreur est également retournée si le SIO_APPLY_TRANSPORT_SETTING IOCTL n’est pas pris en charge par le fournisseur de transport. Cette erreur est également retournée lorsqu’une tentative d’utilisation du SIO_APPLY_TRANSPORT_SETTING IOCTL est effectuée sur un socket autre qu’UDP ou TCP.

Notes

Le SIO_APPLY_TRANSPORT_SETTING IOCTL est pris en charge sur Windows 8, Windows Server 2012 et versions ultérieures du système d’exploitation.

Le SIO_APPLY_TRANSPORT_SETTING IOCTL est un IOCTL générique utilisé pour appliquer le paramètre de transport au socket. Le paramètre de transport appliqué est basé sur la TRANSPORT_SETTING_ID passée dans le paramètre lpvInBuffer .

À partir de Windows 8 et de Windows Server 2012, le système définit la fonctionnalité de REAL_TIME_NOTIFICATION_CAPABILITY sur un socket TCP. À compter de Windows 10 et Windows Server 2016, ASSOCIATE_NAMERES_CONTEXT est également défini. Pour plus d’informations, consultez addrinfoex4 et ASSOCIATE_NAMERES_CONTEXT_INPUT.

Si le TRANSPORT_SETTING_ID passé dans le paramètre lpvInBuffer a le membre GUID défini sur REAL_TIME_NOTIFICATION_CAPABILITY, il s’agit d’une demande d’application des paramètres de notification en temps réel pour le socket TCP utilisé avec ControlChannelTrigger pour recevoir des notifications réseau en arrière-plan dans une application du Windows Store. Le paramètre lpvInBuffer doit pointer vers une structure REAL_TIME_NOTIFICATION_SETTING_INPUT . Le paramètre lpvOutBuffer n’est pas utilisé pour cette opération. Ce paramètre de transport s’applique uniquement aux sockets TCP. Ce paramètre de transport permet à WinInet ou à des services réseau similaires de marquer un socket TCP donné comme étant activé par ControlChannelTrigger . Windows marque le socket TCP correspondant et configure les paramètres matériels et logiciels appropriés lorsque cette option est appelée. Une application du Windows Store n’appelle pas directement ce IOCTL.