WSHGetSocketInformation

INT
WSHGetSocketInformation(
IN PVOID HelperDllSocketContext,
IN SOCKET SocketHandle,
IN HANDLE TdiAddressObjectHandle,
IN HANDLE TdiConnectionObjectHandle,
IN INT Level,
IN INT OptionName,
OUT PCHAR OptionValue,
OUT INT OptionLength
);

WSHGetSocketInformation is called when getsockopt is passed an option that Windows Sockets does not explicitly handle.

Parameters

HelperDllSocketContext: Points to a per-socket context area, allocated and initialized by the WSH DLL WSHOpenSocket or WSHOpenSocket2 function.
SocketHandle: Specifies the handle to the socket returned by socket or accept.
TdiAddressObjectHandle: Specifies the file object handle representing an open transport address associated with the socket, or NULL if the socket is not yet bound to an address. A nonNULL handle allows the WSH DLL to perform operations directly with the transport through the use of this handle.
TdiConnectionObjectHandle: Specifies the file object handle representing an open connection endpoint associated with the socket, or NULL if the socket is a datagram socket or is not yet connected. A nonNULL handle allows the helper DLL to perform operations directly with the transport through the use of this handle.
Level: Specifies the level passed in the getsockopt call.
OptionName: Specifies the optname passed in the getsockopt call. If this is NULL, the Windows Sockets DLL is simply querying the length of the helper DLL’s context information for the socket.
OptionValue: Points to a buffer in which WSHGetSocketInformation returns the requested information.
OptionLength: Points to a variable in which WSHGetSocketInformation returns the number of bytes transferred into the buffer at OptionValue.

Return Value

WSHGetSocketInformation returns zero if it successfully interprets the given option and carries out whatever operation it requires. Otherwise it returns a Windows Sockets error code, the getsockopt call is failed, and its return is set to the error returned by this helper DLL function.

Comments

WSHGetSocketInformation can provide support for arbitrary options beyond those defined by Windows Sockets. Certain defined options also are passed to the helper DLL because of the different ways in which transport drivers provide support for these options, in particular for the SO_KEEPALIVE and SO_DONTROUTE options.

Any option passed in an application call to getsockopt that the Windows Sockets DLL does not recognize is forwarded to WSHGetSocketInformation. The Windows Sockets DLL relies on each helper DLL to fail calls for which the given option is invalid or unsupported by the helper DLL.

WSHGetSocketInformation and WSHSetSocketInformation are also used to support socket handles shared between separate processes. However, the context information maintained by a helper DLL is not automatically shared between processes because virtual memory in a process is private to that process unless both processes set up shared memory.

To support shared socket handles, the Windows Sockets DLL calls WSHGetSocketInformation with the Level SOL_INTERNAL and the OptionName SO_CONTEXT. If necessary, the Windows Sockets DLL calls WSHGetSocketInformation twice: first to determine how large a buffer to allocate for context information and again to get the context information.

Windows Sockets allocates a buffer of the size of the helper DLL's context for the socket before it calls WSHGetSocketInformation with a pointer to the allocated buffer at OptionValue. This call requests WSHGetSocketInformation to retrieve all context information the helper DLL has for the socket. The helper DLL copies its context information into the buffer at OptionValue and returns.

When a socket handle is valid in a new process, either by inheritance of the handle or a call to the Win32 function DuplicateHandle, Windows Sockets first calls WSHOpenSocket or WSHOpenSocket2 in the normal manner to inform the helper DLL that a new socket is being opened. Next Windows Sockets calls WSHSetSocketInformation with the OptionLevel SOL_INTERNAL, the OptionName SO_CONTEXT, and the context information returned by WSHGetSocketInformation in the OptionValue buffer. WSHSetSocketInformation uses the supplied context information to recreate the socket context for the new process.