Expand Minimize

WSAAddressToString function

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 WSAAddressToString(
  _In_      LPSOCKADDR lpsaAddress,
  _In_      DWORD dwAddressLength,
  _In_opt_  LPWSAPROTOCOL_INFO lpProtocolInfo,
  _Inout_   LPTSTR lpszAddressString,
  _Inout_   LPDWORD lpdwAddressStringLength
);

Parameters

lpsaAddress [in]

A pointer to the sockaddr structure to translate into a string.

dwAddressLength [in]

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.

lpProtocolInfo [in, optional]

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.

lpszAddressString [in, out]

A pointer to the buffer that receives the human-readable address string.

lpdwAddressStringLength [in, out]

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 codeMeaning
WSAEFAULT

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.

WSAEINVAL

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.

WSAENOBUFS

No buffer space is available.

WSANOTINITIALISED

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: This API is supported.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winsock2.h

Library

Ws2_32.lib

DLL

Ws2_32.dll

Unicode and ANSI names

WSAAddressToStringW (Unicode) and WSAAddressToStringA (ANSI)

See also

inet_addr
inet_ntoa
InetNtop
InetPton
RtlIpv4AddressToString
RtlIpv4AddressToStringEx
RtlIpv4StringToAddress
RtlIpv4StringToAddressEx
RtlIpv6AddressToString
RtlIpv6AddressToStringEx
RtlIpv6StringToAddress
RtlIpv6StringToAddressEx
sockaddr
WSAStartup
WSAStringToAddress
WSAPROTOCOL_INFO

 

 

Community Additions

ADD
Show:
© 2014 Microsoft