WSAAddressToStringA, fonction (winsock2.h)

Article
08/27/2023

La fonction WSAAddressToString convertit tous les composants d’une structure sockaddr en une représentation sous forme de chaîne lisible par l’utilisateur de l’adresse.

Il est destiné à être utilisé principalement à des fins d’affichage. Si l’appelant exige que la traduction soit effectuée par un fournisseur particulier, il doit fournir la structure WSAPROTOCOL_INFO correspondante dans le paramètre lpProtocolInfo .

Syntaxe

INT WSAAPI WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Paramètres

[in] lpsaAddress

Pointeur vers la structure sockaddr à traduire en chaîne.

[in] dwAddressLength

Longueur, en octets, de l’adresse dans la structure sockaddr pointée par le paramètre lpsaAddress . La taille du paramètre dwAddressLength peut varier selon les protocoles.

[in, optional] lpProtocolInfo

Pointeur vers la structure WSAPROTOCOL_INFO pour un fournisseur particulier. Si le paramètre est NULL, l’appel est routé vers le fournisseur du premier protocole prenant en charge la famille d’adresses indiquée dans le paramètre lpsaAddress .

[in, out] lpszAddressString

Pointeur vers la mémoire tampon qui reçoit la chaîne d’adresse lisible par l’utilisateur.

[in, out] lpdwAddressStringLength

Lors de l’entrée, ce paramètre spécifie la longueur de la mémoire tampon vers laquelle pointe le paramètre lpszAddressString . La longueur est représentée en octets pour les chaînes ANSI et en WCHAR pour les chaînes Unicode. Lors de la sortie, ce paramètre retourne la longueur de la chaîne, y compris la marque de fin NULL réellement copiée dans la mémoire tampon vers laquelle pointe le paramètre lpszAddressString . Si la mémoire tampon spécifiée n’est pas suffisamment grande, la fonction échoue avec une erreur spécifique de WSAEFAULT et ce paramètre est mis à jour avec la taille requise.

Valeur retournée

Si aucune erreur ne se produit, WSAAddressToString retourne une valeur de zéro. 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	Les paramètres lpcsAddress, lpProtocolInfo et lpszAddressString spécifiés pointent vers la mémoire qui n’est pas toutes dans l’espace d’adressage du processus, ou la mémoire tampon vers laquelle pointe le paramètre lpszAddressString est trop petite. Passez une mémoire tampon plus grande.
WSAEINVAL	Un paramètre non valide a été passé. Cette erreur est retournée si le paramètre lpsaAddress, dwAddressLength ou lpdwAddressStringLength est NULL. Cette erreur est également retournée si l’adresse spécifiée n’est pas une adresse de socket valide ou si aucun fournisseur de transport ne prend en charge la famille d’adresses indiquée.
WSAENOBUFS	Aucune zone tampon disponible.
WSANOTINITIALISED	La DLL Winsock 2 n’a pas été initialisée. L’application doit d’abord appeler WSAStartup avant d’appeler les fonctions Windows Sockets.

Remarques

La fonction WSAAddressToString fournit une traduction d’adresse en chaîne indépendante du protocole. La fonction WSAAddressToString prend une structure d’adresse de socket pointée vers le paramètre lpsaAddress et retourne un pointeur vers une chaîne terminée par NULL qui représente l’adresse de socket dans le paramètre lpszAddressString . Alors que la fonction inet_ntoa fonctionne uniquement avec les adresses IPv4, la fonction WSAAddressToString fonctionne avec toute adresse de socket prise en charge par un fournisseur Winsock sur l’ordinateur local, y compris les adresses IPv6.

Si le paramètre lpsaAddress pointe vers une adresse de socket IPv4 (la famille d’adresses est AF_INET), la chaîne d’adresse retournée dans la mémoire tampon vers laquelle pointe le paramètre lpszAddressString est en notation décimale en pointillés comme dans « 192.168.16.0 », un exemple d’adresse IPv4 en notation décimale en pointillés.

Si le paramètre lpsaAddress pointe vers une adresse de socket IPv6 (la famille d’adresses est AF_INET6), la chaîne d’adresse retournée dans la mémoire tampon vers laquelle pointe le paramètre lpszAddressString est au format internet standard. La représentation sous forme de chaîne de base se compose de 8 nombres hexadécimaux séparés par des deux-points. Une chaîne de nombres zéro consécutifs est remplacée par un signe deux-points. Il ne peut y avoir qu’un seul signe deux-points dans la représentation sous forme de chaîne de l’adresse IPv6.

Si la longueur de la mémoire tampon pointée vers par le paramètre lpszAddressString n’est pas suffisamment grande pour recevoir la représentation sous forme de chaîne de l’adresse de socket, WSAAddressToString renvoie WSAEFAULT.

La prise en charge des adresses IPv6 à l’aide de la fonction WSAAddressToString 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 WSAAddressToString prend en charge les adresses IPv6.

Windows Phone 8 : la fonction WSAAddressToStringW est prise en charge pour les applications Windows Phone Store sur Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : la fonction WSAAddressToStringW 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 WSAAddressToString comme 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. La combinaison 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

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