LPFN_RIORECEIVEEX fonction de rappel (mswsock.h)

Article
09/23/2023

La fonction RIOReceiveEx reçoit les données réseau sur un socket TCP d’E/S inscrit connecté ou sur un socket UDP d’E/S inscrit lié avec des options supplémentaires à utiliser avec les extensions d’E/S inscrites winsock.

Syntaxe

LPFN_RIORECEIVEEX LpfnRioreceiveex;

int LpfnRioreceiveex(
                                                                                                                     RIO_RQ SocketQueue,
                                                                                                                     PRIO_BUF pData,
                                                                                                                     ULONG DataBufferCount,
                                                                                                                     PRIO_BUF pLocalAddress,
                                                                                                                     PRIO_BUF pRemoteAddress,
                                                                                                                     PRIO_BUF pControlContext,
                                                                                                                     PRIO_BUF pFlags,
                                                                                                                     DWORD Flags,
                                                                                                                     PVOID RequestContext
)
{...}

Paramètres

SocketQueue

Descripteur qui identifie un socket UDP d’E/S inscrit connecté ou un socket UDP d’E/S inscrit lié.

pData

Description de la partie de la mémoire tampon inscrite dans laquelle recevoir des données.

Ce paramètre peut être NULL pour un socket UDP d’E/S inscrit lié si l’application n’a pas besoin de recevoir une charge utile de données dans le datagramme UDP.

DataBufferCount

Paramètre de nombre de mémoires tampons de données qui indique si les données doivent être reçues dans la mémoire tampon pointée par le paramètre pData .

Ce paramètre doit être défini sur zéro si pData a la valeur NULL. Sinon, ce paramètre doit être défini sur 1.

pLocalAddress

Segment de mémoire tampon qui, à l’achèvement, contiendra l’adresse locale sur laquelle les données réseau ont été reçues.

Ce paramètre peut être NULL si l’application ne souhaite pas recevoir l’adresse locale. Si ce paramètre n’est pas NULL, le segment de mémoire tampon doit avoir au moins la taille d’une structure SOCKADDR_INET .

pRemoteAddress

Segment de mémoire tampon qui, à l’achèvement, contiendra l’adresse distante à partir de laquelle les données réseau ont été reçues.

Ce paramètre peut être NULL si l’application ne souhaite pas recevoir l’adresse distante. Si ce paramètre n’est pas NULL, le segment de mémoire tampon doit avoir au moins la taille d’une structure SOCKADDR_INET .

pControlContext

Tranche de mémoire tampon qui, à l’achèvement, contiendra des informations de contrôle supplémentaires sur l’opération de réception.

Ce paramètre peut être NULL si l’application ne souhaite pas recevoir les informations de contrôle supplémentaires.

pFlags

Flags

Ensemble d’indicateurs qui modifient le comportement de la fonction RIOReceiveEx .

Le paramètre Flags peut contenir une combinaison des options suivantes, définies dans le fichier d’en-tête Mswsockdef.h :

RIO_MSG_COMMIT_ONLY

Les demandes précédentes ajoutées avec RIO_MSG_DEFER indicateur seront validées.

Lorsque l’indicateur RIO_MSG_COMMIT_ONLY est défini, aucun autre indicateur ne peut être spécifié. Lorsque l’indicateur RIO_MSG_COMMIT_ONLY est défini, les arguments pData, pLocalAddress, pRemoteAddress, pControlContext, pFlags et RequestContext doivent être NULL, et l’argument DataBufferCount doit être égal à zéro.

Cet indicateur est normalement utilisé occasionnellement après l’émission d’un certain nombre de demandes avec l’indicateur RIO_MSG_DEFER défini. Cela élimine la nécessité, lors de l’utilisation de l’indicateur RIO_MSG_DEFER , d’effectuer la dernière requête sans l’indicateur RIO_MSG_DEFER , ce qui entraîne la fin de la dernière requête beaucoup plus lentement que les autres requêtes.

Contrairement à d’autres appels à la fonction RIOReceiveEx , lorsque l’indicateur RIO_MSG_COMMIT_ONLY est défini, les appels à la fonction RIOReceiveEx n’ont pas besoin d’être sérialisés. Pour une seule RIO_RQ, la fonction RIOReceiveEx peut être appelée avec RIO_MSG_COMMIT_ONLY sur un thread tout en appelant la fonction RIOReceiveEx sur un autre thread.

RIO_MSG_DONT_NOTIFY

La requête ne doit pas déclencher la fonction RIONotify lorsque l’achèvement de la demande est inséré dans sa file d’attente d’achèvement.

RIO_MSG_DEFER

La demande n’a pas besoin d’être exécutée immédiatement. Cette opération insère la demande dans la file d’attente des requêtes, mais elle peut déclencher ou non l’exécution de la demande.

La réception des données peut être retardée jusqu’à ce qu’une demande de réception soit effectuée sur le RIO_RQ passée dans le paramètre SocketQueue sans l’indicateur RIO_MSG_DEFER défini. Pour déclencher l’exécution de toutes les réceptions dans une file d’attente de requêtes, appelez la fonction RIOReceive ou RIOReceiveEx sans l’indicateur RIO_MSG_DEFER défini.

Notes

La demande de réception est facturée sur la capacité d’E/S en attente sur le RIO_RQ passée dans le paramètre SocketQueue , que RIO_MSG_DEFER soit défini ou non.

RIO_MSG_WAITALL

La fonction RIOReceiveEx ne se termine pas tant que l’un des événements suivants ne se produit pas :

La tranche de mémoire tampon fournie par l’appelant dans le paramètre pData est complètement pleine.
La connexion a été fermée.
La demande a été annulée ou une erreur s’est produite.

Cet indicateur n’est pas pris en charge sur les sockets de datagramme ou sur les sockets sans connexion orientés message.

RequestContext

Contexte de demande à associer à cette opération de réception.

Valeur retournée

Si aucune erreur ne se produit, la fonction RIOReceiveEx retourne TRUE. Dans ce cas, l’opération de réception est lancée avec succès et l’achèvement a déjà été mis en file d’attente ou l’opération a été lancée avec succès et l’achèvement sera mis en file d’attente ultérieurement.

La valeur FALSE indique que la fonction a échoué, que l’opération n’a pas été correctement lancée et qu’aucune indication d’achèvement ne sera mise en file d’attente. Un code d’erreur spécifique peut être récupéré en appelant la fonction WSAGetLastError .

Code de retour	Description
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 si un identificateur de mémoire tampon est désinscrit ou qu’une mémoire tampon est libérée pour l’une des structures RIO_BUF passées dans les paramètres avant que l’opération ne soit mise en file d’attente ou appelée.
WSAEINVAL	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si le paramètre SocketQueue n’est pas valide, si le paramètre dwFlags contient une valeur non valide pour une opération de réception ou si l’intégrité de la file d’attente d’achèvement a été compromise. Cette erreur peut également être retournée pour d’autres problèmes liés aux paramètres.
WSAENOBUFS	La mémoire insuffisante n’a pas pu être allouée. Cette erreur est retournée si la file d’attente d’achèvement des E/S associée au paramètre SocketQueue est pleine ou si la file d’attente d’achèvement des E/S a été créée avec aucune entrée de réception.
WSA_OPERATION_ABORTED	L’opération a été annulée alors que l’opération de réception était en attente. Cette erreur est retournée si le socket est fermé localement ou à distance, ou si la commande SIO_FLUSH dans WSAIoctl est exécutée.

Remarques

Une application peut utiliser la fonction RIOReceiveEx pour recevoir des données réseau dans n’importe quelle mémoire tampon entièrement contenue dans une seule mémoire tampon inscrite. Les membres Offset et Length de la structure RIO_BUF pointées par le paramètre pData déterminent où les données réseau sont reçues dans la mémoire tampon.

Une fois la fonction RIOReceiveEx appelée, la mémoire tampon passée dans le paramètre pData , y compris la RIO_BUFFERID dans le membre BufferId de RIO_BUF structure doit rester valide pendant toute la durée de l’opération de réception.

Pour éviter les conditions de concurrence, une mémoire tampon associée à une demande de réception ne doit pas être lue ou écrite avant la fin de la demande. Cela inclut l’utilisation de la mémoire tampon comme source d’une demande d’envoi ou de destination pour une autre demande de réception. Les parties d’une mémoire tampon inscrite non associées à une demande de réception ne sont pas incluses dans cette restriction.

Le paramètre pLocalAddress peut être utilisé pour récupérer l’adresse locale où les données ont été reçues. Le paramètre pRemoteAddress peut être utilisé pour récupérer l’adresse distante à partir de laquelle les données ont été reçues. Les adresses locales et distantes sont retournées en tant que structures SOCKADDR_INET . Par conséquent, le membre Length du RIO_BUF pointé par les paramètres pLocalAddress ou pRemoteAddress doit être égal ou supérieur à la taille d’une structure SOCKADDR_INET .

Le tableau suivant récapitule les différentes utilisations des données de contrôle disponibles pour une utilisation avec les informations de contrôle dans le membre pControlContext .

Protocol	cmsg_level	cmsg_type	Description
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Reçoit l’interface d’arrivée IPv4 d’origine où le paquet a été reçu pour les sockets de datagramme. Ces données de contrôle sont utilisées par les pare-feu lorsqu’un tunnel Teredo, 6to4 ou ISATAP est utilisé pour la traversée NAT IPv4. Le membre cmsg_data[] est un ULONG qui contient les IF_INDEX définies dans le fichier d’en-tête ifdef.h . Pour plus d’informations, consultez options de socket IPPROTO_IP pour l’option socket IP_ORIGINAL_ARRIVAL_IF.
IPv4	IPPROTO_IP	IP_PKTINFO	Spécifie/reçoit des informations sur les paquets. Pour plus d’informations, consultez options de socket IPPROTO_IP pour l’option de socket IP_PKTINFO.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Spécifie/reçoit les options de destination.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Spécifie/reçoit la limite de tronçon. Pour plus d’informations, consultez options de socket IPPROTO_IPV6 pour l’option de socket IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Spécifie/reçoit les options de tronçon par tronçon.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Spécifie l’adresse du tronçon suivant.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Spécifie/reçoit des informations sur les paquets. Pour plus d’informations, consultez options de socket IPPROTO_IPV6 pour l’option de socket IPV6_PKTINFO.
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Spécifie/reçoit l’en-tête de routage.

Les données de contrôle sont composées d’un ou plusieurs objets de données de contrôle, chacun commençant par une structure WSACMSGHDR , définie comme suit :

} WSACMSGHDR;

Les membres de la structure WSACMSGHDR sont les suivants :

Terme	Description
cmsg_len	Nombre d’octets de données allant du début de WSACMSGHDR à la fin des données (à l’exclusion des octets de remplissage qui peuvent suivre les données).
cmsg_level	Protocole à l’origine des informations de contrôle.
cmsg_type	Type d’informations de contrôle spécifique au protocole.

Le paramètre Flags peut être utilisé pour influencer le comportement de l’appel de la fonction RIOReceiveEx au-delà des options spécifiées pour le socket associé. Le comportement de cette fonction est déterminé par une combinaison d’options de socket définies sur le socket associé au paramètre SocketQueue et les valeurs spécifiées dans le paramètre Flags .

Notes

Le pointeur de la fonction vers la fonction RIOReceiveEx doit être obtenu au moment de l’exécution en appelant la fonction WSAIoctl avec l’opcode SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER spécifié. La mémoire tampon d’entrée passée à la fonction WSAIoctl doit contenir WSAID_MULTIPLE_RIO, un identificateur global unique (GUID) dont la valeur identifie les fonctions d’extension d’E/S inscrites dans Winsock. En cas de réussite, la sortie retournée par la fonction WSAIoctl contient un pointeur vers la structure RIO_EXTENSION_FUNCTION_TABLE qui contient des pointeurs vers les fonctions d’extension d’E/S inscrites dans Winsock. Le SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL est défini dans le fichier d’en-tête Ws2def.h . Le GUID WSAID_MULTIPLE_RIO est défini dans le fichier d’en-tête Mswsock.h .

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

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
En-tête	mswsock.h

Partager via