WSAAddressToStringA function (winsock2.h)
The WSAAddressToString function converts all components of a sockaddr structure into a human-readable string representation of the address.
This is intended to be used mainly for display purposes. If the caller requires that the translation to be performed by a particular provider, it should supply the corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
Syntax
INT WSAAPI WSAAddressToStringA(
[in] LPSOCKADDR lpsaAddress,
[in] DWORD dwAddressLength,
[in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
[in, out] LPSTR lpszAddressString,
[in, out] LPDWORD lpdwAddressStringLength
);
Parameters
[in] lpsaAddress
A pointer to the sockaddr structure to translate into a string.
[in] dwAddressLength
The length, in bytes, of the address in the sockaddr structure pointed to by the lpsaAddress parameter. The dwAddressLength parameter may vary in size with different protocols.
[in, optional] lpProtocolInfo
A pointer to the WSAPROTOCOL_INFO structure for a particular provider. If this is parameter is NULL, the call is routed to the provider of the first protocol supporting the address family indicated in the lpsaAddress parameter.
[in, out] lpszAddressString
A pointer to the buffer that receives the human-readable address string.
[in, out] lpdwAddressStringLength
On input, this parameter specifies the length of the buffer pointed to by the lpszAddressString parameter. The length is represented in bytes for ANSI strings, and in WCHARs for Unicode strings. On output, this parameter returns the length of the string including the NULL terminator actually copied into the buffer pointed to by the lpszAddressString parameter. If the specified buffer is not large enough, the function fails with a specific error of WSAEFAULT and this parameter is updated with the required size.
Return value
If no error occurs, WSAAddressToString returns a value of zero. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.
| Error code | Meaning |
|---|---|
| The specified lpcsAddress, lpProtocolInfo, and lpszAddressString parameters point to memory that is not all in the address space of the process, or the buffer pointed to by the lpszAddressString parameter is too small. Pass in a larger buffer. | |
| An invalid parameter was passed. This error is returned if the lpsaAddress, dwAddressLength, or lpdwAddressStringLength parameter are NULL. This error is also returned if the specified address is not a valid socket address, or no transport provider supports the indicated address family. | |
| No buffer space is available. | |
| The Winsock 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions. |
Remarks
The WSAAddressToString function provides a protocol-independent address-to-string translation. The WSAAddressToString function takes a socket address structure pointed to by the lpsaAddress parameter and returns a pointer to NULL-terminated string that represents the socket address in the lpszAddressString parameter. While the inet_ntoa function works only with IPv4 addresses, the WSAAddressToString function works with any socket address supported by a Winsock provider on the local computer including IPv6 addresses.
If the lpsaAddress parameter points to an IPv4 socket address (the address family is AF_INET), then the address string returned in the buffer pointed to by the lpszAddressString parameter is in dotted-decimal notation as in "192.168.16.0", an example of an IPv4 address in dotted-decimal notation.
If the lpsaAddress parameter points to an IPv6 socket address (the address family is AF_INET6), then the address string returned in the buffer pointed to by the lpszAddressString parameter is in Internet standard format. The basic string representation consists of 8 hexadecimal numbers separated by colons. A string of consecutive zero numbers is replaced with a double-colon. There can only be one double-colon in the string representation of the IPv6 address.
If the length of the buffer pointed to by the lpszAddressString parameter is not large enough to receive the string representation of the socket address, WSAAddressToString returns WSAEFAULT.
Support for IPv6 addresses using the WSAAddressToString function was added on Windows XP with Service Pack 1 (SP1) and later. IPv6 must also be installed on the local computer for the WSAAddressToString function to support IPv6 addresses.
Windows Phone 8: The WSAAddressToStringW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
Windows 8.1 and Windows Server 2012 R2: The WSAAddressToStringW function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.
Note
The winsock2.h header defines WSAAddressToString as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP, Windows 8.1 [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | winsock2.h |
| Library | Ws2_32.lib |
| DLL | Ws2_32.dll |