WSAStringToAddressW function (winsock2.h)

Article
02/09/2023

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 WSAStringToAddressW(
  [in]           LPWSTR              AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOW 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