PFN_WSK_CONTROL_SOCKET fonction de rappel (wsk.h)

Article
02/27/2024

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 de WSK_SOCKET qui spécifie l’objet socket pour le socket sur lequel l’opération de contrôle est effectuée.

[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

Obtient 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 particulière 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 a la valeur WskIoctl, le paramètre ControlCode spécifie l’opération de contrôle d’E/S 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 du 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 auquel 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 protocole de transport ou de socket au niveau du protocole réseau, l’application WSK doit définir ce paramètre au niveau approprié pour le transport sous-jacent.

Si le paramètre RequestType a la valeur WskIoctl, le paramètre Level est ignoré.

[in] InputSize

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

[in, optional] InputBuffer

Mémoire tampon allouée à 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 vers laquelle pointe le paramètre OutputBuffer .

[out, optional] OutputBuffer

Mémoire tampon allouée à 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 de type ULONG qui reçoit le nombre d’octets de données retournés dans la mémoire tampon vers laquelle pointe le paramètre OutputBuffer . Une application WSK doit définir le paramètre OutputSizeReturned sur NULL , sauf lorsque tous les éléments suivants sont true :

Le paramètre Irp a la valeur NULL.
L’opération en cours d’exécution retourne les données de sortie dans la mémoire tampon vers laquelle pointe le paramètre OutputBuffer .
Le nombre d’octets de données de sortie retournées par l’opération effectuée est inconnu.

[in, out] Irp

Pointeur vers un IRP alloué à 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 des irps avec des fonctions WSK, consultez Utilisation des irps avec les fonctions du noyau Winsock.

Si le paramètre RequestType a la valeur WskSetOption ou WskGetOption, le paramètre Irp est obligatoire, est facultatif ou doit avoir la valeur NULL en fonction de l’option de socket en cours de définition ou de récupération. 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 avoir la valeur NULL en fonction de l’opération de contrôle d’E/S en cours d’exécution. Pour plus d’informations sur la configuration requise pour le paramètre Irp pour chacune des opérations de contrôle d’E/S prises en charge, consultez Opérations IOCTL du socket WSK.

Valeur retournée

WskControlSocket retourne l’un des codes NTSTATUS suivants :

Code de retour	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 succès status, et le nombre d’octets retournés dans la mémoire tampon vers laquelle pointe le paramètre OutputBuffer sera retourné dans le champ IoStatus.Information de l’IRP.
STATUS_PENDING	Le sous-système WSK n’a pas pu terminer l’opération de contrôle immédiatement. Le sous-système WSK termine l’IRP une fois l’opération de contrôle terminée. Le status de l’opération de contrôle sera 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 de l’IRP.
STATUS_EVENT_PENDING	Le sous-système WSK n’a pas pu terminer l’opération de contrôle immédiatement. Cette valeur est retournée uniquement lorsqu’une application WSK désactive une fonction de rappel d’événement sur un socket lorsqu’il y a actuellement des appels en cours à cette fonction de rappel d’événement et lorsque le paramètre Irp a la valeur 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 sera terminé avec l’échec status. L’application WSK doit appeler la fonction WskCloseSocket pour fermer le socket dès que possible.
Autres codes status	Une erreur est survenue. L’IRP sera terminé avec l’échec status.

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 l’utilisation des mémoires tampons d’entrée et de sortie pour chaque option de socket.

Si une application WSK spécifie WskIoctl dans le paramètre RequestType , consultez Opérations IOCTL du socket WSK pour plus d’informations sur l’utilisation des tampons d’entrée et de sortie 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 jusqu’à ce que l’IRP soit terminé. Si l’application WSK a alloué les mémoires tampons avec l’une des fonctions ExAllocateXxx , elle ne peut libérer la mémoire avec la fonction ExFreeXxx correspondante qu’une fois l’IRP terminée. 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 tant qu’une fois l’IRP terminée.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Universal
En-tête	wsk.h (inclure Wsk.h)
IRQL	<= DISPATCH_LEVEL (voir la section Remarques)