Fonction de rappel LPWSPACCEPT (ws2spi.h)

Article
08/28/2023

La fonction LPWSPAccept accepte de manière conditionnelle une connexion basée sur la valeur de retour d’une fonction condition.

Syntaxe

LPWSPACCEPT Lpwspaccept;

SOCKET Lpwspaccept(
  [in]      SOCKET s,
  [out]     sockaddr *addr,
  [in, out] LPINT addrlen,
  [in]      LPCONDITIONPROC lpfnCondition,
  [in]      DWORD_PTR dwCallbackData,
  [out]     LPINT lpErrno
)
{...}

Paramètres

[in] s

Descripteur identifiant un socket qui écoute les connexions après un LPWSPListen.

[out] addr

Pointeur facultatif vers une mémoire tampon qui reçoit l’adresse de l’entité de connexion, telle que connue du fournisseur de services. Le format exact du paramètre addr est déterminé par la famille d’adresses établie lors de la création du socket dans la structure sockaddr .

[in, out] addrlen

Pointeur facultatif vers un entier qui contient la longueur du paramètre addr , en octets.

[in] lpfnCondition

Procédure instance adresse d’une fonction de condition facultative fournie par windows Sockets. Cette fonction est utilisée dans la décision d’acceptation ou de rejet en fonction des informations de l’appelant passées en tant que paramètres.

[in] dwCallbackData

Données de rappel à transmettre au client Windows Socket 2 en tant que valeur du paramètre dwCallbackData de la fonction condition. Ce paramètre n’est pas interprété par le fournisseur de services.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, LPWSPAccept retourne une valeur de type SOCKET qui est un descripteur pour le socket accepté. Sinon, une valeur de INVALID_SOCKET est retournée et un code d’erreur spécifique est disponible dans lpErrno.

Code d'erreur	Signification
WSAECONNREFUSED	La demande de connexion a été rejetée de force, comme indiqué dans la valeur de retour de la fonction de condition (CF_REJECT).
WSAECONNRESET	Une connexion entrante a été indiquée, mais a ensuite été arrêtée par l’homologue distant avant d’accepter l’appel.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEFAULT	Le paramètre addrlen est trop petit ou le paramètre lpfnCondition ne fait pas partie de l’espace d’adressage utilisateur.
WSAEINTR	Un appel (bloquant) a été annulé via LPWSPCancelBlockingCall.
WSAEINPROGRESS	Un appel Windows Sockets bloquant est en cours.
WSAEINVAL	LPWSPListen n’a pas été appelé avant LPWSPAccept, le paramètre g spécifié dans la fonction condition n’est pas une valeur valide, la valeur de retour de la fonction condition n’est pas valide, ou tout cas où le socket spécifié est dans un état non valide.
WSAEMFILE	La file d’attente est vide lors de l’entrée dans LPWSPAccept et aucun descripteur de socket n’est disponible.
WSAENOBUFS	Aucune zone tampon disponible.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSAEOPNOTSUPP	Le socket référencé n’est pas un type qui prend en charge le service orienté connexion.
WSATRY_AGAIN	L’acceptation de la demande de connexion a été différée comme indiqué dans la valeur de retour de la fonction de condition (CF_DEFER).
WSAEWOULDBLOCK	Le socket est marqué comme non bloquant et aucune connexion n’est présente pour être acceptée.
WSAEACCES	La demande de connexion proposée a expiré ou a été retirée.

Remarques

La fonction LPWSPAccept extrait la première connexion dans la file d’attente des connexions en attente sur les sockets et la vérifie par rapport à la fonction condition, à condition que la fonction condition soit spécifiée (autrement dit, pas null). La fonction condition doit être exécutée dans le même thread que cette routine. Si la fonction condition retourne CF_ACCEPT, LPWSPAccept crée un socket.

Les sockets nouvellement créés ont les mêmes propriétés que les sockets, y compris les événements réseau inscrits auprès de LPWSPAsyncSelect ou avec LPWSPEventSelect. Comme décrit dans DescriptorAllocation, lorsque de nouveaux descripteurs de socket sont alloués, les fournisseurs IFS doivent appeler WPUModifyIFSHandle et les fournisseurs non-IFS doivent appeler WPUCreateSocketHandle.

Si la fonction condition retourne CF_REJECT, LPWSPAccept rejette la demande de connexion. Si la décision d’acceptation/rejet de l’application ne peut pas être prise immédiatement, la fonction condition retourne CF_DEFER pour indiquer qu’aucune décision n’a été prise. Aucune action concernant cette demande de connexion ne doit être effectuée par le fournisseur de services. Lorsque l’application est prête à agir sur la demande de connexion, elle appelle à nouveau LPWSPAccept et retourne CF_ACCEPT ou CF_REJECT en tant que valeur de retour de la fonction de condition.

Pour les sockets qui sont en mode de blocage (par défaut), si aucune connexion en attente n’est présente dans la file d’attente, LPWSPAccept bloque l’appelant jusqu’à ce qu’une connexion soit présente. Pour les sockets en mode non bloquant, si cette fonction est appelée lorsqu’aucune connexion en attente n’est présente dans la file d’attente, LPWSPAccept retourne le code d’erreur WSAEWOULDBLOCK. Le socket accepté ne peut pas être utilisé pour accepter davantage de connexions. Le socket d’origine reste ouvert.

Le addr de paramètre est un paramètre de résultat qui est rempli avec l’adresse de l’entité de connexion, telle que connue du fournisseur de services. Le format exact du paramètre addr est déterminé par la famille d’adresses dans laquelle la communication se produit. Addrlen est un paramètre value-result ; il contient initialement la quantité d’espace pointée par addr. Au retour, il doit contenir la longueur réelle (en octets) de l’adresse retournée par le fournisseur de services. Cet appel est utilisé avec les types de sockets orientés connexion tels que SOCK_STREAM. Si addr et/ou addrlen sont égaux à null, aucune information sur l’adresse distante du socket accepté n’est retournée. Dans le cas contraire, ces deux paramètres doivent être renseignés, que la fonction de condition soit spécifiée ou ce qu’elle retourne.

Le prototype de la fonction condition est le suivant.

int CALLBACK 
ConditionFunc( 
  IN     LPWSABUF    lpCallerId, 
  IN     LPWSABUF    lpCallerData, 
  IN OUT LPQOS       lpSQOS, 
  IN OUT LPQOS       lpGQOS,
  IN     LPWSABUF    lpCalleeId, 
  IN     LPWSABUF    lpCalleeData, 
  OUT    GROUP FAR * g, 	
  IN     DWORD_PTR   dwCallbackData
);

LpCallerId et lpCallerData sont des paramètres de valeur qui doivent contenir l’adresse de l’entité de connexion et toutes les données utilisateur qui ont été envoyées avec la demande de connexion. Si aucune donnée d’identificateur ou d’appelant n’est disponible, le paramètre correspondant est null. De nombreux protocoles réseau ne prennent pas en charge les données de l’appelant au moment de la connexion. La plupart des protocoles réseau classiques peuvent prendre en charge les informations d’identificateur de l’appelant au moment de la demande de connexion. La partie buf du WSABUF pointée vers lpCallerId pointe vers un sockaddr. Le sockaddr est interprété en fonction de sa famille d’adresses (généralement en castant le sockaddr sur un type spécifique à la famille d’adresses).

Le paramètre lpSQOS fait référence aux spécifications de flux pour les sockets spécifiés par l’appelant, une pour chaque direction, suivie d’autres paramètres spécifiques au fournisseur. Les valeurs de spécification de flux d’envoi ou de réception sont ignorées en fonction des sockets unidirectionnels. Une valeur Null pour lpSQOS indique qu’il n’y a pas de QoS fournie par l’appelant et qu’aucune négociation n’est possible. Un pointeur lpSQOS non NULL indique qu’une négociation QoS doit se produire ou que le fournisseur est prêt à accepter la demande QoS sans négociation.

LpCalleeId est un paramètre de valeur qui contient l’adresse locale de l’entité connectée. La partie buf du WSABUF pointée vers lpCalleeId pointe vers un sockaddr. Le sockaddr est interprété en fonction de sa famille d’adresses (généralement en castant le sockaddr sur un type spécifique à la famille d’adresses).

LpCalleeData est un paramètre de résultat utilisé par la fonction condition pour fournir des données utilisateur à l’entité de connexion. Le stockage de ces données doit être fourni par le fournisseur de services. LpCalleeData-len> contient initialement la longueur de la mémoire tampon allouée par le fournisseur de services et pointée parlpCalleeData-buf.> La valeur zéro signifie que le transfert de données utilisateur à l’appelant n’est pas pris en charge. La fonction condition copie jusqu’à lpCalleeData-len> octets de données dans lpCalleeData-buf>, puis met à jour lpCalleeData-len> pour indiquer le nombre réel d’octets transférés. Si aucune donnée utilisateur ne doit être renvoyée à l’appelant, la fonction condition définit lpCalleeData-len> sur zéro. Le format de toutes les données d’adresse et d’utilisateur est spécifique à la famille d’adresses à laquelle appartient le socket.

La valeur du paramètre dwCallbackData passée à la fonction condition est la valeur passée en tant que paramètre dwCallbackData dans l’appel LPWSPAccept d’origine. Cette valeur est interprétée uniquement par le client Windows Sockets 2. Cela permet à un client de transmettre certaines informations de contexte du site d’appel LPWSPAccept à la fonction condition, qui fournit à la fonction condition toutes les informations supplémentaires requises pour déterminer s’il faut accepter la connexion. Une utilisation classique consiste à passer un pointeur (correctement casté) vers une structure de données contenant des références aux objets définis par l’application auxquels ce socket est associé.

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]
Plateforme cible	Windows
En-tête	ws2spi.h