PFN_WSK_CONTROL_SOCKET fonction de rappel (wsk.h)

Article
02/07/2025

La fonction WskControlSocket effectue des opérations de contrôle sur un socket.

Syntaxe

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

Paramètres

[in] Socket

Pointeur vers une structure WSK_SOCKET qui spécifie l’objet socket pour le socket sur lequel l’opération de contrôle est en cours d’exécution.

[in] RequestType

Valeur qui spécifie le type d’opération de contrôle en cours d’exécution. Une application WSK définit ce paramètre sur l’une des valeurs suivantes :

WskSetOption

Définissez l’état ou la valeur d’une option de socket.

WskGetOption

Obtenez l’état ou la valeur d’une option de socket.

WskIoctl

Effectuez une opération de contrôle d’E/S.

[in] ControlCode

Si le paramètre RequestType est défini sur WskSetOption ou WskGetOption, le paramètre ControlCode spécifie l’option de socket spécifique dont la valeur est définie ou récupérée. Pour plus d’informations sur les options de socket prises en charge par le sous-système WSK, consultez options de socket WSK. Le protocole réseau sous-jacent peut prendre en charge des options de socket supplémentaires.

Si le paramètre RequestType est défini sur WskIoctl, le paramètre ControlCode spécifie l’opération de contrôle d’E/S particulière en cours d’exécution. Pour plus d’informations sur les opérations de contrôle d’E/S prises en charge par le sous-système WSK, consultez opérations IOCTL de socket WSK. Le protocole réseau sous-jacent peut prendre en charge des opérations de contrôle d’E/S de socket supplémentaires.

[in] Level

Niveau de la pile réseau à laquelle la valeur d’une option de socket est définie ou récupérée. Pour les options de socket au niveau du sous-système WSK, l’application WSK doit définir ce paramètre sur SOL_SOCKET. Pour les options de socket au niveau du protocole de transport ou du protocole réseau, l’application WSK doit définir ce paramètre sur le niveau approprié pour le transport sous-jacent.

Si le paramètre RequestType est défini sur WskIoctl, le paramètre Level est ignoré.

[in] InputSize

Nombre d’octets de données dans la mémoire tampon pointant vers le paramètre InputBuffer.

[in, optional] InputBuffer

Mémoire tampon allouée par l’appelant qui fournit toutes les données d’entrée requises pour effectuer l’opération de contrôle spécifiée. Si aucune donnée d’entrée n’est requise pour l’opération de contrôle spécifiée, l’application WSK doit définir ce paramètre sur NULL et définir le paramètre InputSize sur zéro.

[in] OutputSize

Taille de la mémoire tampon pointée par le paramètre OutputBuffer.

[out, optional] OutputBuffer

Mémoire tampon allouée par l’appelant qui reçoit toutes les données de sortie retournées par l’opération de contrôle spécifiée. Si aucune donnée de sortie n’est retournée par l’opération de contrôle spécifiée, l’application WSK doit définir ce paramètre sur NULL et définir le paramètre OutputSize sur zéro.

[out, optional] OutputSizeReturned

Pointeur vers une variable typée ULONG qui reçoit le nombre d’octets de données retournés dans la mémoire tampon pointée par le paramètre OutputBuffer. Une application WSK doit définir le paramètre OutputSizeReturned sur NULL, sauf si toutes les valeurs suivantes sont vraies :

Le paramètre Irp est défini sur NULL.
L’opération en cours d’exécution retourne des données de sortie dans la mémoire tampon pointée par le paramètre OutputBuffer.
Le nombre d’octets des données de sortie retournées par l’opération en cours d’exécution est inconnu.

[in, out] Irp

Pointeur vers un IRP alloué par l’appelant que le sous-système WSK utilise pour terminer l’opération de contrôle de manière asynchrone. Pour plus d’informations sur l’utilisation d’IRPs avec des fonctions WSK, consultez Utilisation d’IRPs avec winsock Kernel Functions.

Si le paramètre RequestType est défini sur WskSetOption ou WskGetOption, le paramètre Irp est obligatoire ou doit être NULL en fonction de l’option de socket spécifique définie ou récupérée. Pour plus d’informations sur la configuration requise pour le paramètre Irp pour chacune des options de socket prises en charge, consultez options de socket WSK.

Si le paramètre RequestType est défini sur WskIoctl, le paramètre Irp est obligatoire, est facultatif ou doit être NULL en fonction de l’opération de contrôle d’E/S particulière en cours d’exécution. Pour plus d’informations sur les exigences relatives au paramètre Irp pour chacune des opérations de contrôle d’E/S prises en charge, consultez opérations IOCTL de socket WSK.

Valeur de retour

WskControlSocket retourne l’un des codes NTSTATUS suivants :

Retourner le code	Description
STATUS_SUCCESS	L’opération de contrôle s’est terminée avec succès. Si l’application WSK a spécifié un pointeur vers un IRP dans le paramètre Irp, l’IRP est terminé avec l’état de réussite, et le nombre d’octets retournés dans la mémoire tampon pointée par le paramètre OutputBuffer est retourné dans le champ IoStatus.Information du protocole IRP.
STATUS_PENDING	Le sous-système WSK n’a pas pu terminer immédiatement l’opération de contrôle. Le sous-système WSK termine l’IRP une fois l’opération de contrôle terminée. L’état de l’opération de contrôle est retourné dans le champ IoStatus.Status de l’IRP. Si l’opération réussit, le nombre d’octets retournés dans la mémoire tampon pointée par le paramètre OutputBuffer est retourné dans le champ IoStatus.Information du protocole IRP.
STATUS_EVENT_PENDING	Le sous-système WSK n’a pas pu terminer immédiatement l’opération de contrôle. Cette valeur est retournée uniquement lorsqu’une application WSK désactive une fonction de rappel d’événement sur un socket lorsqu’il existe actuellement des appels en cours à cette fonction de rappel d’événement et lorsque le paramètre Irp est NULL. Pour plus d’informations sur la désactivation des fonctions de rappel d’événements, consultez SO_WSK_EVENT_CALLBACK.
STATUS_FILE_FORCED_CLOSED	Le socket n’est plus fonctionnel. L’IRP est terminé avec l’état d’échec. L’application WSK doit appeler la fonction WskCloseSocket pour fermer le socket dès que possible.
Autres codes d’état	Une erreur s’est produite. L’IRP est terminé avec l’état d’échec.

Remarques

Si une application WSK spécifie WskSetOption ou WskGetOption dans le paramètre RequestType, consultez options de socket WSK pour plus d’informations sur la façon dont les mémoires tampons d’entrée et de sortie sont utilisées pour chaque option de socket.

Si une application WSK spécifie WskIoctl dans le paramètre RequestType, consultez opérations IOCTL de socket WSK pour plus d’informations sur la façon dont les mémoires tampons d’entrée et de sortie sont utilisées pour chaque opération de contrôle d’E/S.

Si la fonction WskControlSocket retourne STATUS_PENDING, toutes les mémoires tampons pointées par le paramètre InputBuffer ou le paramètre OutputBuffer doivent rester valides tant que l’IRP n’est pas terminé. Si l’application WSK a alloué les mémoires tampons avec l’une des fonctions ExAllocateXxx, elle ne peut pas libérer la mémoire avec la fonction ExFreeXxx correspondante jusqu’à la fin de l’IRP. Si l’application WSK a alloué les mémoires tampons sur la pile, elle ne peut pas retourner à partir de la fonction qui appelle la fonction WskControlSocket jusqu’à la fin de l’IRP.

Les appelants de la fonction WskControlSocket doivent être en cours d’exécution à l'<IRQL = DISPATCH_LEVEL sauf lorsque le paramètre RequestType est défini sur WskIoctl et que le paramètre ControlCode est défini sur SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGEou SIO_ADDRESS_LIST_SORT. Dans ce cas, les appelants doivent s’exécuter à IRQL = PASSIVE_LEVEL.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows Vista et versions ultérieures des systèmes d’exploitation Windows.
plateforme cible	Universel
d’en-tête	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL (voir la section Remarques)