INT
WSHNotify(
IN PVOID HelperDllSocketContext,
IN SOCKET SocketHandle,
IN HANDLE TdiAddressObjectHandle,
IN HANDLE TdiConnectionObjectHandle,
IN DWORD NotifyEvent
);
WSHNotify is called by the Windows Sockets DLL when a socket-state transition occurs for which the helper DLL's WSHOpenSocket or WSHOpenSocket2 function already requested notifications.
The helper DLL's WSHOpenSocket(2) function already selected the set of possible events for which WSHNotify will be called from the preceding values.
WSHNotify returns zero to confirm that the specified state-transition occurred. Otherwise, it returns a Windows Sockets error code. When the return value is nonzero, the application's call to the socket function that would cause a state transition fails and the error is set to the value returned by WSHNotify.
Because WSHNotify is called after all other aspects of a particular state-change succeeded, the socket can be left in a state where the only valid operation is to close the socket when WSHNotify returns an error.
WSHNotify serves two purposes:
For example, the Windows Sockets helper DLL for TCP/IP uses this routine to set a reminder to enable its keep-alive option when an application calls setsockopt before the socket is connected. In these circumstances, no TDI connection object exists when the keep-alive reminder is set, but the helper DLL can actually set the option as soon as the socket becomes connected.
Whenever a helper DLL's WSHNotify function receives a WSH_NOTIFY_CLOSE event, it can free any context it has set up for the socket. After a successful call to WSHNotify with this event, the Windows Sockets DLL never again calls the helper DLL with the same HelperDllSocketContext unless that helper DLL reuses the context areas it allocates. That is, the helper DLL returns the same value from a subsequent call to WSHOpenSocket or WSHOpenSocket2.