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.
INT WSAStringToAddressW(
LPWSTR AddressString,
INT AddressFamily,
LPWSAPROTOCOL_INFOW lpProtocolInfo,
LPSOCKADDR lpAddress,
LPINT lpAddressLength
)
AddressString
Type: LPWSTR
[in]
A pointer to the zero-terminated string that contains the network address in standard text form to convert.
AddressFamily
Type: INT
[in]
The address family of the network address pointed to by the AddressString parameter.
lpProtocolInfo
Type: LPWSAPROTOCOL_INFOW
[in, optional]
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.
lpAddress
Type: LPSOCKADDR
[out]
A pointer to a buffer that is filled with a sockaddr structure for the address string if the function succeeds.
lpAddressLength
Type: LPINT
[in, out]
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.
Type: INT
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.
| Return code | Description |
|---|---|
| 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. |
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 API is supported.
Header: Declared in winsock2.h.
Library: Use ws2_32.lib.