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.
| Code d'erreur | Signification |
|---|---|
| Le sous-système réseau a échoué. | |
| Le paramètre lpFromlen n’était pas valide : la mémoire tampon lpFrom était trop petite pour prendre en charge l’adresse de l’homologue ou lpbuffers n’est pas entièrement contenue dans une partie valide de l’espace d’adressage utilisateur. | |
| L’appel (bloquant) a été annulé via LPWSPCancelBlockingCall. | |
| Le blocage de l’appel Windows Sockets est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Le socket n’a pas été lié (par exemple, avec LPWSPBind) ou le socket n’est pas créé avec l’indicateur qui se chevauche. | |
| Le socket est connecté. Cette fonction n’est pas autorisée avec un socket connecté, que le socket soit orienté connexion ou sans connexion. | |
| La connexion a été interrompue, car l'activité persistante a détecté un échec en cours d'opération. | |
| Le descripteur n’est pas un socket. | |
| MSG_OOB a été spécifié, mais le socket n’est pas de type flux tel que le type SOCK_STREAM, les données OOB ne sont pas prises en charge dans le domaine de communication associé à ce socket, ou le socket est unidirectionnel et prend uniquement en charge les opérations d’envoi. | |
| Le socket a été arrêté ; il n’est pas possible d’exécuter LPWSPRecvFrom sur un socket après l’appel de LPWSPShutdownavec la valeur SD_RECEIVE ou SD_BOTH. | |
|
**Windows NT:** Sockets qui se chevauchent : il y a trop de demandes d’E/S qui se chevauchent en attente. Sockets non bloqués : le socket est marqué comme non bloquant et l’opération de réception ne peut pas être effectuée immédiatement. |
|
| Le message était trop volumineux pour tenir dans la mémoire tampon spécifiée et (pour les protocoles non fiables uniquement) toute partie de fin du message qui ne tient pas dans la mémoire tampon a été ignorée. | |
| Le circuit virtuel a été rétabli par la partie distante exécutant une fermeture brutale ou infructueuse. L’application doit fermer le socket, car il n’est plus utilisable. Sur un socket de datagramme UDP, cette erreur indique qu’une opération d’envoi précédente a entraîné un message ICMP « Port inaccessible ». | |
| Le socket est orienté message et le circuit virtuel a été correctement fermé par le côté distant. | |
| Une opération superposée a été lancée avec succès et l’achèvement sera indiqué ultérieurement. | |
| L’opération qui se chevauche a été annulée en raison de la fermeture du socket. |
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.
| Valeur | Signification |
|---|---|
| MSG_PEEK | Jetez un coup d’œil aux données entrantes. Les données sont copiées dans la mémoire tampon, mais ne sont pas supprimées de la file d’attente d’entrée. Cet indicateur est valide uniquement pour les sockets non survolés. |
| MSG_OOB | Traite les données hors bande (OOB). |
| MSG_PARTIAL | Cet indicateur s’adresse uniquement aux sockets orientés message. Sur la sortie, indique que les données fournies sont une partie du message transmis par l’expéditeur. Les parties restantes du message seront fournies dans les opérations de réception suivantes. Une opération de réception ultérieure avec MSG_PARTIAL indicateur effacé indique la fin du message de l’expéditeur. En tant que paramètre d’entrée, MSG_PARTIAL indique que l’opération de réception doit se terminer même si seule une partie d’un message a été reçue par le fournisseur de services. |
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.
Notes
Toutes les E/S initiées par un thread donné sont annulées à la sortie de ce thread. Pour les sockets qui se chevauchent, les opérations asynchrones en attente peuvent échouer si le thread est fermé avant la fin des opérations. Pour plus d’informations, consultez ExitThread .
Spécifications
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| En-tête | ws2spi.h |