Fonction WSAStringToAddressA (winsock2.h)

Article
08/27/2023

La fonction WSAStringToAddress convertit une adresse réseau dans son formulaire de présentation de texte standard en sa forme binaire numérique dans une structure sockaddr , adaptée pour passer aux routines Windows Sockets qui prennent une telle structure.

Syntaxe

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

Paramètres

[in] AddressString

Pointeur vers la chaîne à terminaison zéro qui contient l’adresse réseau sous forme de texte standard à convertir.

[in] AddressFamily

Famille d’adresses de l’adresse réseau pointée vers le paramètre AddressString .

[in, optional] lpProtocolInfo

Structure WSAPROTOCOL_INFO associée au fournisseur à utiliser. Si cette valeur est NULL, l’appel est routé vers le fournisseur du premier protocole prenant en charge la propriété AddressFamily indiquée.

[out] lpAddress

Pointeur vers une mémoire tampon remplie d’une structure sockaddr pour la chaîne d’adresse si la fonction réussit.

[in, out] lpAddressLength

Pointeur vers la longueur, en octets, de la mémoire tampon pointée vers le paramètre lpAddress . Si l’appel de fonction réussit, ce paramètre retourne un pointeur vers la taille de la structure sockaddr retournée dans le paramètre lpAddress . Si la mémoire tampon spécifiée 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.

Valeur retournée

La valeur de retour pour WSAStringToAddress est zéro si l’opération a réussi. Sinon, la valeur SOCKET_ERROR est retournée et un numéro d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur	Signification
WSAEFAULT	La mémoire tampon pointée vers le paramètre lpAddress est trop petite. Transmettez une mémoire tampon plus grande.
WSAEINVAL	Les fonctions n’ont pas pu traduire la chaîne en sockaddr. Pour plus d’informations, consultez la section Remarques suivante.
WSANOTINITIALISED	Le WS2_32.DLL n’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler les fonctions de socket Windows.
WSA_NOT_ENOUGH_MEMORY	La mémoire était insuffisante pour effectuer l’opération.

Remarques

La fonction WSAStringToAddress convertit une adresse réseau sous forme de texte standard en sa forme binaire numérique dans une structure sockaddr .

Si possible, tous les composants manquants de l’adresse seront traités par défaut à une valeur raisonnable. Par exemple, un numéro de port manquant est égal à zéro par défaut. Si l’appelant souhaite que la traduction soit effectuée par un fournisseur particulier, il doit fournir la structure WSAPROTOCOL_INFO correspondante dans le paramètre lpProtocolInfo .

La fonction WSAStringToAddress échoue (et retourne WSAEINVAL) si le membre sin_family de la structure SOCKADDR_IN , qui est transmis dans le paramètre lpAddress sous la forme d’une structure sockaddr , n’est pas défini sur AF_INET ou AF_INET6.

La prise en charge des adresses IPv6 à l’aide de la fonction WSAStringToAddress a été ajoutée sur Windows XP avec Service Pack 1 (SP1) et versions ultérieures. IPv6 doit également être installé sur l’ordinateur local pour que la fonction WSAStringToAddress puisse prendre en charge les adresses IPv6.

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Notes

L’en-tête winsock2.h définit WSAStringToAddress comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll