Fonction de rappel LPWSPACCEPT (ws2spi.h)

Article
07/16/2024

La fonction LPWSPAccept accepte conditionnellement une connexion en fonction de la valeur de retour d’une fonction de 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, comme connu pour le fournisseur de services. Le format exact du paramètre de du module complémentaire est déterminé par la famille d’adresses établie lorsque le socket dans la structure sockaddr a été créée.

[in, out] addrlen

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

[in] lpfnCondition

Adresse d’instance de procédure 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 transmises en tant que paramètres.

[in] dwCallbackData

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

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur de retour

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 avec 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 é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, paramètre g spécifié dans la fonction de 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 n’est pas vide lors de l’entrée à LPWSPAccept et aucun descripteur de socket n’est disponible.
WSAENOBUFS	Aucun espace tampon n’est 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 qui a été proposée a expiré ou a été retirée.

Remarques

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

Les sockets nouvellement créés ont les mêmes propriétés que lesdu socket , 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 de 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 à prendre des mesures sur la demande de connexion, elle appelle LPWSPAccept à nouveau et retourne CF_ACCEPT ou CF_REJECT comme valeur de retour de la fonction de condition.

Pour les sockets qui se trouvent en mode de blocage (par défaut), si aucune connexion en attente n’est présente dans la file d’attente, LPWSPAc cept 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 paramètre addr est un paramètre de résultat rempli avec l’adresse de l’entité de connexion, comme connu pour le fournisseur de services. Le format exact du paramètre addr est déterminé par la famille d’adresses dans laquelle la communication se produit. Le addrlen est un paramètre value-result ; il contiendra 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 des types de sockets orientés connexion tels que SOCK_STREAM. Si addr et/ou addrlen sont égales à 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 de 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
);

Les 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 envoyées avec la demande de connexion. Si aucune donnée d’appelant 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 d’appelant au moment de la connexion. La plupart des protocoles réseau conventionnels peuvent être censés prendre en charge les informations d’identificateur de l’appelant au moment de la demande de connexion. La partie WSABUF pointée par lpCallerId pointe vers unsockaddr . Le sockaddr est interprété en fonction de sa famille d’adresses (généralement en faisant passer le sockaddr à un type spécifique à la famille d’adresses).

Le paramètre lpSQOS fait référence aux spécifications de flux pour les de socket spécifiées par l’appelant, une pour chaque direction, suivie de tous les paramètres supplémentaires 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’existe aucune QoS fournie par l’appelant et qu’aucune négociation n’est possible. Un pointeur nullNULLlpSQOS indique qu’une négociation QoS doit se produire ou que le fournisseur est prêt à accepter la demande QoS sans négociation.

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

L'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. Le lpCalleeData->len contient initialement la longueur de la mémoire tampon allouée par le fournisseur de services et pointée par lpCalleeData->buf . La valeur zéro signifie que le passage de données utilisateur à l’appelant n’est pas pris en charge. La fonction de condition copie jusqu’à lpCalleeData-> octets de données dans lpCalleeData->buf, puis mettez à jour lpCalleeData->len pour indiquer le nombre réel d’octets transférés. Si aucune donnée utilisateur n’est transmise à l’appelant, la fonction de 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 de 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 à partir de l'LPWSPAccept appeler le site à l’aide de la fonction de condition, qui fournit à la fonction de condition toutes les informations supplémentaires requises pour déterminer s’il faut accepter la connexion. Une utilisation classique consiste à passer un pointeur (casté de manière appropriée) à une structure de données contenant des références à des objets définis par l’application avec lesquels ce socket est associé.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	ws2spi.h