LPWSPADDRESSTOSTRING callback function (ws2spi.h)

Article
02/22/2024

The LPWSPAddressToString function converts all components of a sockaddr structure into a human-readable numeric string representation of the address. This is used mainly for display purposes.

Syntax

LPWSPADDRESSTOSTRING Lpwspaddresstostring;

INT Lpwspaddresstostring(
  [in]      LPSOCKADDR lpsaAddress,
  [in]      DWORD dwAddressLength,
  [in]      LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [out]     LPWSTR lpszAddressString,
  [in, out] LPDWORD lpdwAddressStringLength,
  [out]     LPINT lpErrno
)
{...}

Parameters

[in] lpsaAddress

Pointer to a sockaddr structure to translate into a string.

[in] dwAddressLength

Length of the address of sockaddr, in bytes.

[in] lpProtocolInfo

(required) WSAProtocol_Info structure associated with the provider that will do the translation.

[out] lpszAddressString

Buffer that receives the human-readable address string..

[in, out] lpdwAddressStringLength

Length of the AddressString buffer, in bytes. Returns the length of the string actually copied into the buffer. 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.

[out] lpErrno

Pointer to the error code.

Return value

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

Error code	Meaning
WSAEFAULT	The specified AddressString buffer is too small. Pass in a larger buffer.
WSAEINVAL	The specified address is not a valid socket address, or its address family is not supported by the provider, or the specified lpProtocolInfo did not refer to a WSAProtocol_Info structure supported by the provider.

Remarks

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

If the next layer in the protocol chain is another layer, then, when the next layer's LPWSPAddressToString is called, this layer must pass to the next layer a lpProtocolInfo parameter that references the same unmodified WSAProtocol_Info structure 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 LPWSPAddressToString. In this case, the base provider's WSAPROTOCOL_INFO structure should be referenced by the lpProtocolInfo parameter. One vital benefit of this policy is that base service providers do not have to be aware of protocol chains.

This same propagation policy applies when propagating a WSAProtocol_Info structure through a layered sequence of other functions such as LPWSPDuplicateSocket, WSPStartup, LPWSPSocket, or LPWSPStringToAddress.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	ws2spi.h