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 all parts of a sockaddrstructure into a human readable–numeric string representation of the address. This is used mainly for display purposes.

Syntax 

int WSPAddressToString(
  LPSOCKADDR 
lpsaAddress,
  DWORD 
dwAddressLength,
  LPWSAPROTOCOL_INFOW 
lpProtocolInfo,
  LPWSTR 
lpszAddressString,
  LPDWORD 
lpdwAddressStringLength,
  LPINT 
lpErrno 
);

Parameters

lpsaAddress

[in] Points to a sockaddrstructure to translate into a string.

dwAddressLength

[in] Length of the address sockaddr.

lpProtocolInfo

[in] (required) WSAPROTOCOL_INFOstructure associated with the provider that will do the translation.

lpszAddressString

[out] Buffer that receives the human readable–address string.

lpdwAddressStringLength

[in, out] On input, the length of the AddressStringbuffer in characters. On output, returns the length of the string actually copied into the buffer including the terminating NULL character. 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 string length in characters.

lpErrno

[out] Pointer to the error code.

Return Value

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

Error value Description

WSAEFAULT

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

WSA_EINVAL

Specified Address is not a valid socket address, or its address family is not supported by the provider, or the specified lpProtocolInfodid not refer to a WSAPROTOCOL_INFOstructure 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 WSPAddressToStringof the next layer in the provider chain. Some special considerations apply to the lpProtocolInfoparameter as it is propagated down through the layers of the provider chain.

When a layer follows another layer in a provider chain the first layer must pass to the next a lpProtocolInfoparameter when the second layer's WSPAddressToStringfunction is called. The lpProtocolInfoparameter should reference a WSAPROTOCOL_INFOstructure with 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 WSPAddressToString. In this case, the base provider's WSAPROTOCOL_INFOstructure 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_INFOstructure through a layered sequence of other functions such as WSPDuplicateSocket, WSPStartup, WSPSocket, or WSPStringToAddress.

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