Fonction de rappel LPWSPSTRINGTOADDRESS (ws2spi.h)

Article
08/28/2023

La fonction WSPStringToAddress convertit une chaîne numérique lisible par l’homme en une structure d’adresse de socket (sockaddr) appropriée pour passer aux routines windows Sockets qui prennent une telle structure. Si possible, tous les composants manquants de l’adresse ont une valeur raisonnable. Par exemple, un numéro de port manquant est égal par défaut à zéro.

Syntaxe

LPWSPSTRINGTOADDRESS Lpwspstringtoaddress;

INT Lpwspstringtoaddress(
  [in]      LPWSTR AddressString,
  [in]      INT AddressFamily,
  [in]      LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [out]     LPSOCKADDR lpAddress,
  [in, out] LPINT lpAddressLength,
  [out]     LPINT lpErrno
)
{...}

Paramètres

[in] AddressString

Pointeur vers la chaîne sans fin et lisible par l’homme à convertir.

[in] AddressFamily

Adressez la famille à laquelle la chaîne appartient ou AF_UNSPEC si elle est inconnue.

[in] lpProtocolInfo

(obligatoire) Structure WSAProtocol_Info du fournisseur.

[out] lpAddress

Mémoire tampon remplie avec une seule structure de sockaddr .

[in, out] lpAddressLength

Longueur de la mémoire tampon d’adresse, en octets. Retourne la taille de la structure sockaddr résultante. Si la mémoire tampon fournie n’est pas assez grande, la fonction échoue avec une erreur spécifique de WSAEFAULT et ce paramètre est mis à jour avec la taille requise en octets.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, WSPStringToAddress retourne zéro. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique est disponible dans lpErrno.

Code d'erreur	Signification
WSAEFAULT	La mémoire tampon d’adresse spécifiée est trop petite, transmettez une mémoire tampon plus grande.
WSAEINVAL	Impossible de traduire la chaîne en un sockaddr, ou le fournisseur n’a pas pu prendre en charge la famille d’adresses indiquée, ou le lpProtocolInfo spécifié ne faisait pas référence à une structure WSAProtocol_Info prise en charge par le fournisseur.

Remarques

Un fournisseur de services en couche fournit une implémentation de cette fonction, mais il est également un client de cette fonction si et quand il appelle WSPStringToAddress de la couche suivante dans la chaîne de protocole. Certaines considérations spéciales s’appliquent au paramètre lpProtocolInfo de cette fonction, car il est propagé vers le bas via les couches de la chaîne de protocole.

Si la couche suivante de la chaîne de protocole est une autre couche, lorsque la couche WSPStringToAddress de la couche suivante est appelée, cette couche doit passer à la couche suivante un lpProtocolInfo qui fait référence à la même structure de WSAProtocol_Info non modifiée avec les mêmes informations de chaîne non modifiées. Toutefois, si la couche suivante est le protocole de base (c’est-à-dire le dernier élément de la chaîne), cette couche effectue une substitution lors de l’appel de WSPStringToAddress du fournisseur de base. Dans ce cas, la structure WSAPROTOCOL_INFO du fournisseur de base doit être référencée par le paramètre lpProtocolInfo .

L’un des avantages essentiels de cette stratégie est que les fournisseurs de services de base n’ont pas besoin de connaître les chaînes de protocoles.

Cette même stratégie de propagation s’applique lors de la propagation d’une structure de WSAProtocol_Info via une séquence en couches d’autres fonctions telles que LPWSPAddressToString, LPWSPDuplicateSocket, WSPStartup ou LPWSPSocket.

Configuration requise

Condition requise	Valeur
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