LPFN_RIOSENDEX fonction de rappel (mswsock.h)
La fonction RIOSendEx envoie des 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_RIOSENDEX LpfnRiosendex;
BOOL LpfnRiosendex(
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 TCP d’E/S inscrit connecté ou un socket UDP d’E/S inscrit lié.
pData
Segment de mémoire tampon à partir d’une mémoire tampon inscrite à partir de laquelle envoyer des données. La structure RIO_BUF pointée par ce paramètre peut représenter une partie d’une mémoire tampon inscrite ou une mémoire tampon inscrite complète.
Ce paramètre peut être NULL pour un socket UDP d’E/S inscrit lié si l’application n’a pas besoin d’envoyer 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 envoyées 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
Ce paramètre est réservé et doit être NULL.
pRemoteAddress
Segment de mémoire tampon d’une mémoire tampon inscrite qui, sur l’entrée, contient l’adresse distante à laquelle les données réseau doivent être envoyées.
Ce paramètre peut être NULL si le socket est connecté.
pControlContext
Tranche de mémoire tampon qui, à l’achèvement, contiendra des informations de contrôle supplémentaires sur l’opération d’envoi.
Ce paramètre peut être NULL si l’application ne souhaite pas recevoir les informations de contrôle supplémentaires.
pFlags
Tranche de mémoire tampon qui, à l’achèvement, contiendra des informations supplémentaires sur l’ensemble d’indicateurs pour l’opération d’envoi.
Ce paramètre peut être NULL si l’application ne souhaite pas recevoir les informations supplémentaires sur les indicateurs.
Flags
Ensemble d’indicateurs qui modifient le comportement de la fonction RIOSendEx .
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 RIOSendEx , lorsque l’indicateur RIO_MSG_COMMIT_ONLY est défini, les appels à la fonction RIOSendEx n’ont pas besoin d’être sérialisés. Pour une seule RIO_RQ, la fonction RIOSendEx peut être appelée avec RIO_MSG_COMMIT_ONLY sur un thread tout en appelant la fonction RIOSendEx 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.
L’envoi de données peut être retardé jusqu’à ce qu’une demande d’envoi soit effectuée sur le RIO_RQ passé dans le paramètre SocketQueue sans l’indicateur RIO_MSG_DEFER défini. Pour déclencher l’exécution de tous les envois dans une file d’attente d’envoi, appelez la fonction RIOSend ou RIOSendEx sans l’indicateur RIO_MSG_DEFER défini.
Notes
La demande d’envoi 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.
RequestContext
Contexte de demande à associer à cette opération d’envoi.
Valeur retournée
Si aucune erreur ne se produit, la fonction RIOSendEx retourne TRUE. Dans ce cas, l’opération d’envoi 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 d’envoi 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 zéro entrée d’envoi. |
| WSA_IO_PENDING | L’opération a été lancée avec succès et l’achèvement sera mis en file d’attente ultérieurement. |
Remarques
Une application peut utiliser la fonction RIOSendEx pour envoyer des données réseau à partir de 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 les données réseau à envoyer à partir de la mémoire tampon.
La mémoire tampon associée à une opération d’envoi ne doit pas être utilisée simultanément avec une autre opération d’envoi ou de réception. La mémoire tampon et l’inscription de la mémoire tampon doivent rester valides pendant la durée d’une opération d’envoi. Cela signifie que vous ne devez pas passer les mêmes PRIO_BUF à une requête RIOSend(Ex) quand une requête est déjà en attente. Une fois qu’une demande RIOSend(Ex) en cours d’exécution est terminée, vous devez réutiliser le même PRIO_BUF (avec le même décalage ou avec un décalage et une longueur différents). En outre, lorsque l’envoi de données fait référence à une mémoire tampon inscrite (une partie ou la mémoire tampon entière), la mémoire tampon inscrite entière ne doit pas être utilisée tant que l’envoi n’est pas terminé. Cela inclut l’utilisation d’une partie de la mémoire tampon inscrite pour une opération de réception ou une autre opération d’envoi.
Le paramètre pLocalAddress peut être utilisé pour récupérer l’adresse locale à partir de laquelle les données ont été envoyées. Le paramètre pRemoteAddress peut être utilisé pour récupérer l’adresse distante à laquelle les données ont été envoyées. 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_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çons. 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 constitué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 commençant du début de WSACMSGHDR à la fin des données (à l’exception 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 la fonction RIOSendEx 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 RIOSendEx doit être obtenu au moment de l’exécution en effectuant un appel à la fonction WSAIoctl avec le SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode 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 |