Expand Minimize

WSAStringToAddress function

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 WSAStringToAddress(
  _In_      LPTSTR AddressString,
  _In_      INT AddressFamily,
  _In_opt_  LPWSAPROTOCOL_INFO lpProtocolInfo,
  _Out_     LPSOCKADDR lpAddress,
  _Inout_   LPINT lpAddressLength
);

Parameters

AddressString [in]

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

AddressFamily [in]

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

lpProtocolInfo [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 [out]

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

lpAddressLength [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.

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

Requirements

Minimum supported client

Windows 8.1, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Minimum supported phone

Windows Phone 8

Header

Winsock2.h

Library

Ws2_32.lib

DLL

Ws2_32.dll

Unicode and ANSI names

WSAStringToAddressW (Unicode) and WSAStringToAddressA (ANSI)

See also

inet_addr
inet_ntoa
InetNtop
InetPton
RtlIpv4AddressToString
RtlIpv4AddressToStringEx
RtlIpv4StringToAddress
RtlIpv4StringToAddressEx
RtlIpv6AddressToString
RtlIpv6AddressToStringEx
RtlIpv6StringToAddress
RtlIpv6StringToAddressEx
sockaddr
WSAAddressToString
WSAPROTOCOL_INFO
WSAStartup

 

 

Community Additions

ADD
Show:
© 2014 Microsoft