WSAAddressToStringA, fonction (winsock2.h)
La fonction WSAAddressToString convertit tous les composants d’une structure sockaddr en une représentation sous forme de chaîne lisible par l’homme 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 vers le paramètre lpsaAddress . La taille du paramètre dwAddressLength peut varier en fonction des protocoles.
[in, optional] lpProtocolInfo
Pointeur vers la structure WSAPROTOCOL_INFO pour un fournisseur particulier. S’il s’agit d’un paramètre 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
En entrée, ce paramètre spécifie la longueur de la mémoire tampon pointée vers 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 terminaison NULL réellement copiée dans la mémoire tampon pointée vers le paramètre lpszAddressString . 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.
Valeur retournée
Si aucune erreur ne se produit, WSAAddressToString retourne la valeur 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 |
|---|---|
| Les paramètres lpcsAddress, lpProtocolInfo et lpszAddressString spécifiés pointent vers la mémoire qui n’est pas tout dans l’espace d’adressage du processus, ou la mémoire tampon pointée par le paramètre lpszAddressString est trop petite. Transmettez une mémoire tampon plus grande. | |
| 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. | |
| Aucune zone tampon disponible. | |
| 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 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 n’importe quelle 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 renvoyé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 renvoyée dans la mémoire tampon vers laquelle pointe le paramètre lpszAddressString est au format Internet standard. La représentation de chaîne de base se compose de 8 nombres hexadécimaux séparés par des points-virgules. 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 retourne 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 puisse prendre en charge les adresses IPv6.
Windows Phone 8 : La fonction WSAAddressToStringW est prise en charge pour les applications du 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 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
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP, Windows 8.1 [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 |