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
);

Parameter

• 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.

Rückgabewert

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.

Hinweise

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 mit Service Pack 1 (SP1) and later. IPv6 must also be installed on the local computer for the WSAAddressToString function to support IPv6 addresses.

Anforderungen

Siehe auch

inet_addr

inet_ntoa

InetNtop

InetPton

RtlIpv4AddressToString

RtlIpv4AddressToStringEx

RtlIpv4StringToAddress

RtlIpv4StringToAddressEx

RtlIpv6AddressToString

RtlIpv6AddressToStringEx

RtlIpv6StringToAddress

RtlIpv6StringToAddressEx

sockaddr

WSAStartup

WSAStringToAddress

WSAPROTOCOL_INFO