WSAStringToAddressA function (winsock2.h)

The WSAStringToAddress function converts a network address in its standard text presentation form into its numeric binary form in a sockaddr structure, suitable for passing to Windows Sockets routines that take such a structure.

Syntax

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

Parameters

[in] AddressString

A pointer to the zero-terminated string that contains the network address in standard text form to convert.

[in] AddressFamily

The address family of the network address pointed to by the AddressString parameter.

[in, optional] lpProtocolInfo

The WSAPROTOCOL_INFO structure associated with the provider to be used. If this is NULL, the call is routed to the provider of the first protocol supporting the indicated AddressFamily.

[out] lpAddress

A pointer to a buffer that is filled with a sockaddr structure for the address string if the function succeeds.

[in, out] lpAddressLength

A pointer to the length, in bytes, of the buffer pointed to by the lpAddress parameter. If the function call is successful, this parameter returns a pointer to the size of the sockaddr structure returned in the lpAddress 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 in bytes.

Return value

The return value for WSAStringToAddress is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.

Error code Meaning
WSAEFAULT
The buffer pointed to by the lpAddress parameter is too small. Pass in a larger buffer.
WSAEINVAL
The functions was unable to translate the string into a sockaddr. See the following Remarks section for more information.
WSANOTINITIALISED
The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Socket functions.
WSA_NOT_ENOUGH_MEMORY
There was insufficient memory to perform the operation.

Remarks

The WSAStringToAddress function converts a network address in standard text form into its numeric binary form in a sockaddr structure.

Any missing components of the address will be defaulted to a reasonable value, if possible. For example, a missing port number will default to zero. If the caller wants the translation to be done by a particular provider, it should supply the corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.

The WSAStringToAddress function fails (and returns WSAEINVAL) if the sin_family member of the SOCKADDR_IN structure, which is passed in the lpAddress parameter in the form of a sockaddr structure, is not set to AF_INET or AF_INET6.

Support for IPv6 addresses using the WSAStringToAddress function was added on Windows XP with Service Pack 1 (SP1)and later. IPv6 must also be installed on the local computer for the WSAStringToAddress function to support IPv6 addresses.

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Note

The winsock2.h header defines WSAStringToAddress 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 8.1, Windows Vista [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

See also

InetNtop

InetPton

RtlIpv4AddressToString

RtlIpv4AddressToStringEx

RtlIpv4StringToAddress

RtlIpv4StringToAddressEx

RtlIpv6AddressToString

RtlIpv6AddressToStringEx

RtlIpv6StringToAddress

RtlIpv6StringToAddressEx

WSAAddressToString

WSAPROTOCOL_INFO

WSAStartup

inet_addr

inet_ntoa

sockaddr