LPFN_RIONOTIFY fonction de rappel (mswsock.h)

La fonction RIONotify inscrit la méthode à utiliser pour le comportement de notification avec une file d’attente d’achèvement d’E/S à utiliser avec les extensions d’E/S inscrites dans Winsock.

Syntaxe

LPFN_RIONOTIFY LpfnRionotify;

INT LpfnRionotify(
  RIO_CQ CQ
)
{...}

Paramètres

CQ

Descripteur qui identifie une file d’attente d’achèvement des E/S.

Valeur retournée

Si aucune erreur ne se produit, la fonction RIONotify retourne ERROR_SUCCESS. Sinon, la fonction a échoué et un code d’erreur spécifique est retourné.

Code de retour	Description
WSAEINVAL	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si la file d’attente d’achèvement non valide est passée dans le paramètre CQ (RIO_INVALID_CQ, par exemple). Cette erreur peut également être retournée lorsqu’une erreur interne se produit.
WSAEALREADY	Tentative d'opération sur un socket non bloquant au niveau duquel une opération était déjà en cours. Cette erreur est retournée si une requête RIONotify précédente n’est pas encore terminée.

Remarques

La fonction RIONotify enregistre la méthode à utiliser pour le comportement de notification pour l’envoi ou la réception de données réseau avec les extensions d’E/S inscrites winsock.

La fonction RIONotify est le mécanisme par lequel une application détecte que les demandes sont terminées et attendent un appel à la fonction RIODequeueCompletion . La fonction RIONotify définit la méthode à utiliser pour le comportement de notification lorsqu’une file d’attente d’achèvement d’E/S n’est pas vide et contient l’achèvement d’un résultat.

Le comportement de notification d’une file d’attente d’achèvement est défini lors de la création du RIO_CQ . La structure RIO_NOTIFICATION_COMPLETION est passée à la fonction RIOCreateCompletionQueue lorsqu’une RIO_CQ est créée.

Pour une file d’attente d’achèvement qui utilise un événement, le membre Type de la structure RIO_NOTIFICATION_COMPLETION est défini sur RIO_EVENT_COMPLETION. Le membre Event.EventHandle doit contenir le handle d’un événement créé par la fonction WSACreateEvent ou CreateEvent . Pour recevoir l’achèvement RIONotify , l’application doit attendre le handle d’événement spécifié à l’aide de WSAWaitForMultipleEvents ou d’une routine d’attente similaire. Si l’application prévoit de réinitialiser et de réutiliser l’événement, l’application peut réduire la surcharge en définissant le membre Event.NotifyReset sur une valeur différente de zéro. Cela entraîne la réinitialisation automatique de l’événement par la fonction RIONotify lorsque la notification se produit. Cela atténue la nécessité d’appeler la fonction WSAResetEvent pour réinitialiser l’événement entre les appels à la fonction RIONotify .

Lorsque la fonction RIONotify est appelée saisie semi-automatique des événements utilisés et que la file d’attente d’achèvement spécifiée n’est pas déjà vide, l’événement est défini de manière synchrone ou asynchrone. Dans les deux cas, les entrées supplémentaires n’ont pas besoin d’entrer dans la file d’attente d’achèvement avant que l’événement soit défini. Tant que la file d’attente d’achèvement ne contient pas l’achèvement d’une requête qui n’a pas l’indicateur RIO_MSG_DONT_NOTIFY défini, la file d’attente d’achèvement est considérée comme vide aux fins de la fonction RIONotify et l’événement n’est pas défini. Toutes les demandes terminées peuvent toujours être récupérées à l’aide de la fonction RIODequeueCompletion . Lorsque l’événement est défini, l’application appelle généralement la fonction RIODequeueCompletion pour mettre en file d’attente les demandes d’envoi et de réception terminées.

Pour une file d’attente d’achèvement qui utilise un port d’achèvement des E/S, le membre Type de la structure RIO_NOTIFICATION_COMPLETION est défini sur RIO_IOCP_COMPLETION. Le membre Iocp.IocpHandle doit contenir le handle d’un port d’achèvement d’E/S créé par la fonction CreateIoCompletionPort . Pour recevoir l’achèvement RIONotify , l’application doit appeler la fonction GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . L’application doit fournir un objet OVERLAPPED dédié pour la file d’attente d’achèvement, et elle peut également utiliser le membre Iocp.CompletionKey pour distinguer les demandes RIONotify sur la file d’attente d’achèvement des autres complétions d’E/S, y compris les saisies semi-automatique RIONotify pour d’autres files d’attente d’achèvement.

Une application utilisant des pools de threads peut utiliser des objets d’attente de pool de threads pour obtenir des achèvements RIONotify via son pool de threads. Dans ce cas, l’appel à la fonction SetThreadpoolWait doit suivre immédiatement l’appel à RIONotify. Si la fonction SetThreadpoolWait est appelée avant RIONotify et que l’application s’appuie sur RIONotify pour effacer l’objet d’événement, cela peut entraîner des exécutions erronées du rappel de l’objet wait.

Notes

Le pointeur de fonction vers la fonction RIONotify 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.

Cohérence de thread

Si plusieurs threads tentent d’accéder au même RIO_CQ à l’aide de la fonction RIODequeueCompletion , l’accès doit être coordonné par une section critique, un verrou d’enregistreur de lecture mince ou un mécanisme d’exclusion mutuelle similaire. Si les files d’attente d’achèvement ne sont pas partagées, l’exclusion mutuelle n’est pas requise.

Configuration requise

Condition requise	Valeur
En-tête	mswsock.h