SO_WSK_EVENT_CALLBACK

The SO_WSK_EVENT_CALLBACK socket option allows a WSK application to enable and disable a socket's event callback functions. This socket option applies only to listening sockets, datagram sockets, connection-oriented sockets, and basic sockets that have registered an extension interface for which at least one event callback function is defined.

If a WSK application uses this socket option to enable or disable event callback functions on either a listening socket or a datagram socket, it must do so after the socket has been bound to a local transport address.

If a WSK application uses this socket option to enable or disable event callback functions on a connection-oriented socket, it must do so after the socket has been connected to a remote transport address.

To enable or disable event callback functions on a socket, a WSK application calls the WskControlSocket function with the following parameters.

A WSK application does not specify a pointer to an IRP when calling the WskControlSocket function to enable event callback functions on a socket.

A WSK application can optionally specify a pointer to an IRP when calling the WskControlSocket function to disable an event callback function on a socket.

When a WSK application calls WskControlSocket to disable an event callback function, the WSK subsystem behaves as follows:

• If there are no in-progress calls to the event callback function that is being disabled when the WSK application calls the WskControlSocket function, the event callback function is disabled and the WskControlSocket function returns STATUS_SUCCESS. If the WSK application specifies an IRP, the IRP is completed with success status.

• If there are in-progress calls to the event callback function that is being disabled when the WSK application calls the WskControlSocket function and the WSK application specified an IRP, the WskControlSocket function returns STATUS_PENDING. The WSK subsystem disables the event callback function and completes the IRP after all in-progress calls to the event callback function have returned.

• If there are in-progress calls to the event callback function that is being disabled when the WSK application calls the WskControlSocket function and the WSK application did not specify an IRP, the WskControlSocket function returns STATUS_EVENT_PENDING. The WSK subsystem disables the event callback function after all in-progress calls to the event callback function have returned.

When enabling or disabling any of the standard WSK event callback functions, a WSK application sets the NpiId member of the WSK_EVENT_CALLBACK_CONTROL structure to a pointer to the WSK Network Programming Interface (NPI) identifier, NPI_WSK_INTERFACE_ID.

When enabling or disabling any callback functions for an extension interface, a WSK application sets the NpiId member of the WSK_EVENT_CALLBACK_CONTROL structure to a pointer to the NPI identifier for that extension interface.

When enabling event callback functions, a WSK application can simultaneously enable any combination of the event callback functions that are valid for a particular category of WSK socket. The WSK application simultaneously enables these combinations by setting the EventMask member of the WSK_EVENT_CALLBACK_CONTROL structure to a bitwise OR of the event flags for all of the event callback functions that are being enabled.

When disabling event callback functions, a WSK application must disable each event callback function independently. A WSK application independently disables an event callback function by setting the EventMask member of the WSK_EVENT_CALLBACK_CONTROL structure to a bitwise OR of the event flag for the event callback function that is being disabled and the WSK_EVENT_DISABLE flag.

The following table shows the valid event flags for a listening socket.

The following table shows the valid event flags for a datagram socket.

The following table shows the valid event flags for a connection-oriented socket.

A listening socket can automatically enable event callback functions on connection-oriented sockets that are accepted by the listening socket. A WSK application automatically enables these callback functions by enabling the connection-oriented socket event callback functions on the listening socket. The event callback functions are automatically enabled on an accepted connection-oriented socket only if the socket is accepted by the listening socket's WskAcceptEvent event callback function. If the connection-oriented socket is accepted by the listening socket's WskAccept function, the accepted socket's event callback functions are not automatically enabled.

After any connection-oriented event callback functions are enabled on a listening socket, they cannot be disabled on the listening socket. If the WskAcceptEvent event callback function is disabled and then re-enabled on a listening socket, any connection-oriented event callback functions that were originally enabled on that listening socket will continue to be applied to all connection-oriented sockets that are accepted by the WskAcceptEvent event callback function.

For more information about enabling and disabling a socket's event callback functions, see Enabling and Disabling Event Callback Functions.

Requirements