Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function converts a human-readable numeric string to a socket address structure ( sockaddr) suitable to passing to Windows Sockets routines that take such a structure.

Any missing part of the address will be defaulted to a reasonable value if possible. For example, a missing port number will default to zero.

Syntax 

int WSPStringToAddress (
  LPWSTR 
AddressString,
  INT 
AddressFamily,
  LPWSAPROTOCOL_INFOW 
lpProtocolInfo,
  LPSOCKADDR 
lpAddress,
  LPINT 
lpAddressLength,
  LPINT 
lpErrno 
);

Parameters

AddressString

[in] Points to the zero-terminated human-readable string to convert.

AddressFamily

[in] Address family to which the string belongs, or AF_UNSPEC if it is unknown.

lpProtocolInfo

[in] (required) Provider's WSAPROTOCOL_INFOWstructure.

lpAddress

[out] Buffer that is filled with a single sockaddrstructure.

lpAddressLength

[in, out] Length of the Address buffer. Returns the size of the resultant sockaddrstructure. If the supplied 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.

lpErrno

[out] Pointer to the error code.

Return Value

If no error occurs, this function returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code is available in lpErrno.

The following table shows the possible error codes.

Error value Description

WSAEFAULT

Specified address buffer is too small. Pass in a larger buffer.

WSAEINVAL

Unable to translate the string into a sockaddr, or the provider was unable to support the indicated address family, or the specified lpProtocolInfodid not refer to a WSAPROTOCOL_INFOWstructure supported by the provider.

Layered Service Provider Considerations

A layered service provider supplies an implementation of this function, but it is also a client of this function if and when it calls WSPStringToAddressof the next layer in the provider chain. Some special considerations apply to this function's lpProtocolInfoparameter as it is propagated down through the layers of the provider chain.

If the next layer in the provider chain is another layer then when the next layer's WSPStringToAddressis called, this layer must pass to the next layer a lpProtocolInfothat references the same unmodified WSAPROTOCOL_INFOWstructure with the same unmodified chain information. However, if the next layer is the base protocol (that is, the last element in the chain), this layer performs a substitution when calling the base provider's WSPStringToAddress. In this case, the base provider's WSAPROTOCOL_INFOWstructure should be referenced by the lpProtocolInfoparameter.

One vital benefit of this policy is that base service providers do not have to be aware of provider chains.

This same propagation policy applies when propagating a WSAPROTOCOL_INFOWstructure through a layered sequence of other functions such as WSPAddressToString, WSPDuplicateSocket, WSPStartup, or WSPSocket.

Requirements

Header ws2spi.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also