LPWSPSTRINGTOADDRESS callback function (ws2spi.h)
The WSPStringToAddress 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 components of the address are defaulted to a reasonable value, if possible. For example, a missing port number defaults to zero.
Syntax
LPWSPSTRINGTOADDRESS Lpwspstringtoaddress;
INT Lpwspstringtoaddress(
[in] LPWSTR AddressString,
[in] INT AddressFamily,
[in] LPWSAPROTOCOL_INFOW lpProtocolInfo,
[out] LPSOCKADDR lpAddress,
[in, out] LPINT lpAddressLength,
[out] LPINT lpErrno
)
{...}
Parameters
[in] AddressString
Pointer to the zero-terminated, human-readable string to convert.
[in] AddressFamily
Address family to which the string belongs, or AF_UNSPEC if it is unknown.
[in] lpProtocolInfo
(required) Provider's WSAProtocol_Info structure.
[out] lpAddress
Buffer that is filled with a single sockaddr structure.
[in, out] lpAddressLength
Length of the Address buffer, in bytes. Returns the size of the resultant sockaddr structure. 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, WSPStringToAddress returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code is available in lpErrno.
| Error code | Meaning |
|---|---|
| The specified address buffer is too small, pass in a larger buffer. | |
| Unable to translate the string into a sockaddr, or the provider was unable to support the indicated address family, 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 WSPStringToAddress of the next layer in the protocol chain. Some special considerations apply to this function's 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 WSPStringToAddress is called, this layer must pass to the next layer a lpProtocolInfo 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 WSPStringToAddress. 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 LPWSPAddressToString, LPWSPDuplicateSocket, WSPStartup, or LPWSPSocket.
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 |