LPWSPRECVFROM, fonction de rappel (ws2spi.h)

La fonction LPWSPRecvFrom reçoit un datagramme et stocke l’adresse source.

Syntaxe

LPWSPRECVFROM Lpwsprecvfrom;

int Lpwsprecvfrom(
  [in]      SOCKET s,
  [in, out] LPWSABUF lpBuffers,
  [in]      DWORD dwBufferCount,
  [out]     LPDWORD lpNumberOfBytesRecvd,
  [in, out] LPDWORD lpFlags,
  [out]     sockaddr *lpFrom,
  [in, out] LPINT lpFromlen,
  [in]      LPWSAOVERLAPPED lpOverlapped,
  [in]      LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  \[in\]    LPWSATHREADID lpThreadId,
  [in, out] LPINT lpErrno
)
{...}

Paramètres

[in] s

Descripteur identifiant un socket.

[in, out] lpBuffers

Pointeur vers un tableau de structures WSABUF . Chaque structure WSABUF contient un pointeur vers une mémoire tampon et la longueur de la mémoire tampon, en octets.

[in] dwBufferCount

Nombre de structures WSABUF dans le tableau lpBuffers .

[out] lpNumberOfBytesRecvd

Pointeur vers le nombre d’octets reçus par cet appel.

[in, out] lpFlags

Pointeur vers des indicateurs.

[out] lpFrom

Pointeur facultatif vers une mémoire tampon dans la structure sockaddr qui contiendra l’adresse source à la fin de l’opération qui se chevauche.

[in, out] lpFromlen

Pointeur vers la taille de la mémoire tampon lpFrom , en octets, requise uniquement si lpFrom est spécifié.

[in] lpOverlapped

Pointeur vers une structure WSAOverlapped (ignoré pour les sockets non inexploités).

[in] lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération de réception terminée (ignorée pour les sockets non exécutés).

\\[in\\] lpThreadId

Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (pas le pointeur vers le même) jusqu’à ce que la fonction WPUQueueApc soit retournée.

[in, out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit et que l’opération de réception s’est terminée immédiatement, LPWSPRecvFrom retourne zéro. Notez que dans ce cas, la routine d’achèvement, si elle est spécifiée, a déjà été mise en file d’attente. Sinon, la valeur SOCKET_ERROR est retournée et un code d’erreur spécifique est disponible dans lpErrno. Le code d’erreur WSA_IO_PENDING indique que l’opération qui se chevauche a été correctement lancée et que l’achèvement sera indiqué ultérieurement. Tout autre code d’erreur indique qu’aucune opération qui se chevauche n’a été lancée et qu’aucune indication d’achèvement ne se produira.

Remarques

La fonction LPWSPRecvFrom est principalement utilisée sur un socket sans connexion spécifié par s Le socket ne doit pas être connecté. L’adresse locale du socket doit être connue. Cela peut être fait explicitement via LPWSPBind ou implicitement via LPWSPSendTo ou LPWSPJoinLeaf.

Pour les sockets qui se chevauchent, cette fonction est utilisée pour publier une ou plusieurs mémoires tampons dans lesquelles les données entrantes seront placées à mesure qu’elles seront disponibles sur un socket (éventuellement connecté), après quoi l’indication d’achèvement spécifiée par le client (appel de la routine d’achèvement ou du paramètre d’un objet événement) se produit. Si l’opération ne se termine pas immédiatement, la status d’achèvement finale est récupérée via la routine d’achèvement ou LPWSPGetOverlappedResult. Notez également que les valeurs pointées par lpFrom et lpFromlen ne sont pas mises à jour tant que l’achèvement n’est pas indiqué. Les applications ne doivent pas utiliser ou déranger ces valeurs tant qu’elles n’ont pas été mises à jour. Par conséquent, le client ne doit pas utiliser de variables automatiques (c’est-à-dire basées sur la pile) pour ces paramètres.

Si lpOverlapped et lpCompletionRoutine sont tous deux null, le socket dans cette fonction est traité comme un socket non inexploité.

Pour les sockets non inexploités, les paramètres lpOverlapped, lpCompletionRoutine et lpThreadId sont ignorés. Toutes les données qui ont déjà été reçues et mises en mémoire tampon par le transport sont copiées dans les mémoires tampons utilisateur fournies. Dans le cas d’un socket bloquant sans aucune donnée actuellement reçue et mise en mémoire tampon par le transport, l’appel se bloque jusqu’à ce que les données sont reçues en fonction de la sémantique de blocage affectée pour LPWSPRecv.

Les mémoires tampons fournies sont remplies dans l’ordre dans lequel elles apparaissent dans le tableau pointé par lpBuffers, et les tampons sont emballés de sorte qu’aucun trou ne soit créé.

Le tableau de structures WSABUF pointées par le paramètre lpBuffers est temporaire. Si cette opération se termine de manière chevauchée, il incombe au fournisseur de services de capturer ce tableau de pointeurs vers les structures WSABUF avant de revenir à partir de cet appel. Cela permet aux clients SPI Windows Sockets de créer des tableaux WSABUF basés sur une pile.

Pour les types de sockets sans connexion, l’adresse à partir de laquelle les données proviennent est copiée dans la mémoire tampon pointée par lpFrom. Lors de l’entrée, la valeur pointée par lpFromlen est initialisée à la taille de cette mémoire tampon et est modifiée à l’achèvement pour indiquer la taille réelle de l’adresse qui y est stockée.

Comme indiqué précédemment pour les sockets qui se chevauchent, les paramètres lpFrom et lpFromlen ne sont pas mis à jour tant que les E/S superposées ne sont pas terminées. La mémoire pointée par ces paramètres doit donc rester disponible pour le fournisseur de services et ne peut pas être allouée sur la trame de pile du client SPI Windows Sockets. Les paramètres lpFrom et lpFromlen sont ignorés pour les sockets orientés connexion.

Pour les sockets de type flux d’octets (par exemple, type SOCK_STREAM), les données entrantes sont placées dans les mémoires tampons jusqu’à ce que les mémoires tampons soient remplies, que la connexion soit fermée ou que les données mises en mémoire tampon en interne soient épuisées. Que les données entrantes remplissent ou non toutes les mémoires tampons, l’indication d’achèvement se produit pour les sockets qui se chevauchent.

Pour les sockets orientés messages, un seul message entrant est placé dans les mémoires tampons fournies, jusqu’à la taille totale des mémoires tampons fournies, et l’indication d’achèvement se produit pour les sockets superposés. Si le message est plus grand que les mémoires tampons fournies, les mémoires tampons sont remplies avec la première partie du message. Si la fonctionnalité MSG_PARTIAL est prise en charge par le fournisseur de services, l’indicateur de MSG_PARTIAL est défini dans lpFlags pour le socket et les opérations de réception suivantes récupèrent le reste du message. Si MSG_PARTIAL n’est pas pris en charge mais que le protocole est fiable, LPWSPRecvFrom génère l’erreur WSAEMSGSIZE et une opération de réception ultérieure avec une mémoire tampon plus grande peut être utilisée pour récupérer l’intégralité du message. Sinon, (autrement dit, le protocole n’est pas fiable et ne prend pas en charge MSG_PARTIAL), les données excédentaires sont perdues et LPWSPRecvFrom génère l’erreur WSAEMSGSIZE.

Le paramètre lpFlags peut être utilisé pour influencer le comportement de l’appel de fonction au-delà des options spécifiées pour le socket associé. Autrement dit, la sémantique de cette fonction est déterminée par les options de socket et le paramètre lpFlags . Ce dernier est construit à l’aide de l’opérateur OR au niveau du bit avec l’une des valeurs suivantes.

Pour les sockets orientés message, le bit MSG_PARTIAL est défini dans le paramètre lpFlags si un message partiel est reçu. Si un message complet est reçu, MSG_PARTIAL est effacé dans lpFlags. En cas d’achèvement différé, la valeur pointée par lpFlags n’est pas mise à jour. Lorsque l’achèvement a été indiqué, le client SPI Windows Sockets doit appeler LPWSPGetOverlappedResult et examiner les indicateurs pointés par le paramètre lpdwFlags .

Si une opération qui se chevauche se termine immédiatement, LPWSPRecv retourne la valeur zéro et le paramètre lpNumberOfBytesRecvd est mis à jour avec le nombre d’octets reçus et les bits d’indicateur pointés par le paramètre lpFlags sont également mis à jour. Si l’opération qui se chevauche est correctement lancée et se terminera ultérieurement, LPWSPRecv retourne SOCKET_ERROR et indique le code d’erreur WSA_IO_PENDING. Dans ce cas, lpNumberOfBytesRecvd et lpFlags ne sont pas mis à jour. Une fois l’opération qui se chevauche, la quantité de données transférées est indiquée via le paramètre cbTransferred dans la routine d’achèvement (si spécifié), ou via le paramètre lpcbTransfer dans LPWSPGetOverlappedResult. Les valeurs d’indicateur sont obtenues en examinant le paramètre lpdwFlags de LPWSPGetOverlappedResult.

Les fournisseurs doivent autoriser l’appel de cette fonction à partir de la routine d’achèvement d’une fonction LPWSPRecv,LPWSPRecvFrom, LPWSPSend ou LPWSPSendTo précédente. Toutefois, pour un socket donné, les routines d’achèvement d’E/S ne peuvent pas être imbriquées. Cela permet aux transmissions de données sensibles au temps de se produire entièrement dans un contexte préemptif.

Le paramètre lpOverlapped doit être valide pendant la durée de l’opération qui se chevauche. Si plusieurs opérations d’E/S sont simultanément en attente, chacune doit référencer une structure distincte qui se chevauche. La structure WSAOverlapped est définie dans sa propre page de référence.

Si le paramètre lpCompletionRoutine est null, le fournisseur de services signale le membre hEvent de lpOverlapped lorsque l’opération qui se chevauche se termine s’il contient un handle d’objet d’événement valide. Un client SPI windows Sockets peut utiliser LPWSPGetOverlappedResult pour attendre ou interroger l’objet d’événement.

Si lpCompletionRoutine n’est pas null, le membre hEvent est ignoré et peut être utilisé par le client SPI windows Sockets pour transmettre des informations de contexte à la routine d’achèvement. Il incombe au fournisseur de services d’organiser l’appel de la routine d’achèvement spécifiée par le client une fois l’opération qui se chevauche. Étant donné que la routine d’achèvement doit être exécutée dans le contexte du même thread que celui qui a lancé l’opération chevauchée, elle ne peut pas être appelée directement à partir du fournisseur de services. Le Ws2_32.dll offre un mécanisme d’appel de procédure asynchrone (APC) pour faciliter l’appel des routines d’achèvement.

Un fournisseur de services organise l’exécution d’une fonction dans le contexte de thread et de processus appropriés en appelant WPUQueueApc. Cette fonction peut être appelée à partir de n’importe quel processus et contexte de thread, même un contexte différent du thread et du processus utilisé pour lancer l’opération qui se chevauche.

WPUQueueApc prend comme paramètres d’entrée un pointeur vers une structure WSATHREADID (fournie au fournisseur via le paramètre d’entrée lpThreadId ), un pointeur vers une fonction APC à appeler et une valeur de contexte qui est ensuite passée à la fonction APC. Étant donné qu’une seule valeur de contexte est disponible, la fonction APC elle-même ne peut pas être la routine d’achèvement spécifiée par le client. Le fournisseur de services doit à la place fournir un pointeur vers sa propre fonction APC qui utilise la valeur de contexte fournie pour accéder aux informations de résultat nécessaires pour l’opération qui se chevauche, puis appelle la routine d’achèvement spécifiée par le client.

Le prototype de la routine d’achèvement fournie par le client est le suivant :

void CALLBACK 
CompletionRoutine(  
  IN DWORD           dwError, 
  IN DWORD           cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD           dwFlags 
);

CompletionRoutine est un espace réservé pour un nom de fonction fourni par le client. dwError spécifie le status d’achèvement pour l’opération qui se chevauche, comme indiqué par lpOverlapped. cbTransferred spécifie le nombre d’octets reçus. dwFlags contient des informations qui auraient été affichées dans lpFlags si l’opération de réception s’était terminée immédiatement. Cette fonction ne retourne pas de valeur.

Les routines d’achèvement peuvent être appelées dans n’importe quel ordre, mais pas nécessairement dans le même ordre que celui où les opérations se chevauchent. Toutefois, il est garanti que les mémoires tampons publiées soient remplies dans la même commande qu’elles sont fournies.

Spécifications

Voir aussi

WPUQueueApc

LPWSPGetOverlappedResult

LPWSPSocket