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 |
|---|---|
| The buffer pointed to by the lpAddress parameter is too small. Pass in a larger buffer. | |
| The functions was unable to translate the string into a sockaddr. See the following Remarks section for more information. | |
| The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Socket functions. | |
| 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 that 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 is 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 |