WSHNotify

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.

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 handle to a file object representing the open transport address for the socket. If the socket is not currently bound to an address, this parameter is NULL.

TdiConnectionObjectHandle

Specifies the handle to a file object representing the connection endpoint associated with the socket. If the socket is not currently connected, this parameter is NULL.

NotifyEvent

Specifies the state change that just occurred. Exactly one bit of the WSH_NOTIFY_XXX values, defined in wsahelp.h, is set in this parameter at each call to WSHNotify. The WSH_NOTIFY_XXX values include the following:

WSH_NOTIFY_BIND

A successful call to bind occurred.

WSH_NOTIFY_LISTEN

A successful call to listen occurred.

WSH_NOTIFY_ACCEPT

A socket handle is being returned from a call to accept.

WSH_NOTIFY_CONNECT

A successful call to connect occurred.

WSH_NOTIFY_SHUTDOWN_RECEIVE

A successful call to shutdown for the receive side of the socket occurred.

WSH_NOTIFY_SHUTDOWN_SEND

A successful call to shutdown for the send side of the socket occurred.

WSH_NOTIFY_SHUTDOWN_ALL

A successful call to shutdown for both sides of the socket occurred.

WSH_NOTIFY_CLOSE

The socket is being closed.

WSH_NOTIFY_CONNECT_ERROR

A failed call to WSAConnect or connect.

The helper DLL's WSHOpenSocket(2) function already selected the set of possible events for which WSHNotify will be called from the preceding values.

Return Value

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.

Comments

WSHNotify serves two purposes:

1. To allow a helper DLL to track the state of a socket

2. To give a helper DLL an opportunity to support options requiring the socket to be in a specific state

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.

See Also

WSHOpenSocket, WSHOpenSocket2