WSHGetWildcardSockaddr

INT
   WSHGetWildcardSockaddr(
       IN PVOID HelperDllSocketContext,
       OUT PSOCKADDR Sockaddr,
       OUT PINT SockaddrLength
       );

WSHGetWildcardSockaddr returns a socket address that can be used to bind a socket to an arbitrary or wildcard address.

Parameters

HelperDllSocketContext

Points to a per-socket context area, allocated and initialized by the WSH DLL WSHOpenSocket or WSHOpenSocket2 function.

Sockaddr

Points to a buffer in which the helper DLL returns the socket address, formatted in a SOCKADDR structure.

SockaddrLength

Specifies the length in bytes of the buffer at Sockaddr.

Return Value

WSHGetWildcardSockaddr returns zero if it returned an address at Sockaddr. If it could not determine a value for the wildcard address, it returns a WSAXXX error code.

Comments

Windows Sockets calls WSHGetWildcardSockaddr when it needs to perform an automatic bind of a socket. Such a bind is necessary when an application, typically a client-side application, requests an operation that requires a handle to a file object representing a transport address but that application has not bound the socket to an address.

For example, an application that calls either connect or sendto without having called bind causes a call to WSHGetWildcardSockAddr because the Windows Sockets DLL must bind the socket to an arbitrary local address. In these circumstances, WSHGetWildcardSockaddr returns any address that can be used for this bind, while Windows Sockets uses the returned address.

If a transport does not support automatic binds to an arbitrary address, the helper DLL's WSHGetWildcardSockaddr either can fail all calls or the helper DLL can simply not export this function. Such a tranport requires Windows Sockets applications running over that transport to always bind before making any calls to Windows Sockets functions that require a bound socket.