LPFN_RIORECEIVE fonction de rappel (mswsock.h)

  • Article

La fonction RIOReceive reçoit des données réseau sur un socket TCP d’E/S inscrit connecté ou un socket UDP d’E/S inscrit lié pour une utilisation avec les extensions d’E/S inscrites winsock.

Syntaxe

LPFN_RIORECEIVE LpfnRioreceive;

BOOL LpfnRioreceive(
  RIO_RQ SocketQueue,
  PRIO_BUF pData,
  ULONG DataBufferCount,
  DWORD Flags,
  PVOID RequestContext
)
{...}

Paramètres

SocketQueue

Descripteur qui identifie un socket TCP 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 la 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.

Flags

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

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 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 RIOReceive , lorsque l’indicateur RIO_MSG_COMMIT_ONLY est défini, les appels à la fonction RIOReceive n’ont pas besoin d’être sérialisés. Pour une seule RIO_RQ, la fonction RIOReceive peut être appelée avec RIO_MSG_COMMIT_ONLY sur un thread tout en appelant la fonction RIOReceive 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 RIOReceive ne se termine pas tant que l’un des événements suivants ne se produit pas :

  • Le segment de mémoire tampon fourni par l’appelant dans le paramètre pData est complètement plein.
  • 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 UDP.

RequestContext

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

Valeur retournée

Si aucune erreur ne se produit, la fonction RIOReceive 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 Flags 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 sur ce socket.

Remarques

Une application peut utiliser la fonction RIOReceive pour recevoir des données réseau dans n’importe quelle mémoire tampon entièrement contenue dans une mémoire tampon inscrite unique. 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 RIOReceive 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 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 Flags peut être utilisé pour influencer le comportement de l’appel de la fonction RIOReceive 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 des valeurs spécifiées dans le paramètre Flags .

Notes

Le pointeur de fonction vers la fonction RIOReceive doit être obtenu au moment de l’exécution en effectuant un appel à 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 Windows Phone Store sur 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