PFN_WSK_RECEIVE_FROM_EVENT callback function (wsk.h)

Article
10/21/2021

The WskReceiveFromEvent event callback function notifies a WSK application that one or more datagrams have been received on a datagram socket.

Syntax

PFN_WSK_RECEIVE_FROM_EVENT PfnWskReceiveFromEvent;

NTSTATUS PfnWskReceiveFromEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATAGRAM_INDICATION DataIndication
)
{...}

Parameters

[in, optional] SocketContext

A pointer to the socket context for the datagram socket that has received the datagrams. The WSK application provided this pointer to the WSK subsystem when it called the WskSocket function to create the datagram socket.

[in] Flags

A ULONG value that contains a bitwise OR of a combination of the following flags:

MSG_BCAST

The datagrams were received as a link-layer broadcast or with a destination transport address that is a broadcast address.

MSG_MCAST

The datagrams were received with a destination transport address that is a multicast address.

WSK_FLAG_AT_DISPATCH_LEVEL

The WSK subsystem called the WskReceiveFromEvent event callback function at IRQL = DISPATCH_LEVEL. If this flag is not set, the WSK subsystem might have called the WskReceiveFromEvent event callback function at any IRQL <= DISPATCH_LEVEL.

[in, optional] DataIndication

A pointer to a linked list of WSK_DATAGRAM_INDICATION structures that describe the received datagrams. If this parameter is NULL, the socket is no longer functional and the WSK application must call the WskCloseSocket function to close the socket as soon as possible.

Return value

A WSK application's WskReceiveFromEvent event callback function can return one of the following NTSTATUS codes:

Return code	Description
STATUS_SUCCESS	The WSK application accepted the datagrams and retrieved all of the datagrams from the linked list of WSK_DATAGRAM_INDICATION structures. The WSK subsystem can call the WskReceiveFromEvent event callback function again when new datagrams are received on the socket.
STATUS_PENDING	The WSK application accepted the datagrams but did not retrieve all of the datagrams from the linked list of WSK_DATAGRAM_INDICATION structures. The WSK application retains the linked list of WSK_DATAGRAM_INDICATION structures until all of the datagrams have been retrieved. After the WSK application has retrieved all of the datagrams, it calls the WskRelease function to release the linked list of WSK_DATAGRAM_INDICATION structures back to the WSK subsystem. The WSK subsystem can call the WskReceiveFromEvent event callback function again when new datagrams are received on the socket.
STATUS_DATA_NOT_ACCEPTED	The WSK application did not accept the datagrams. If a WSK application returns this status code, the WSK subsystem will respond differently depending on how the WSK application enabled the WskReceiveFromEvent event callback function. If the WSK application enabled the WskReceiveFromEvent event callback function by using the SO_WSK_EVENT_CALLBACK socket option, the WSK subsystem will have the underlying transport buffer the datagrams if possible or if otherwise required by the protocol. The WSK subsystem will disable the WskReceiveFromEvent event callback function and will not call the WskReceiveFromEvent event callback function again until after the WSK application re-enables this event callback function with the SO_WSK_EVENT_CALLBACK socket option. After the WSK application has re-enabled the WskReceiveFromEvent event callback function, the WSK subsystem will resume calling the WskReceiveFromEvent event callback function with any remaining buffered datagrams and when new datagrams are received on the socket. If the WSK application enabled the WskReceiveFromEvent event callback function by using the WSK_SET_STATIC_EVENT_CALLBACKS client control operation, the WSK subsystem will not disable the WskReceiveFromEvent event callback function. The WSK subsystem will continue calling the WskReceiveFromEvent event callback function when new datagrams are received on the socket.

Remarks

The WSK subsystem calls a WSK application's WskReceiveFromEvent event callback function when new datagrams are received on a datagram socket only if the event callback function was previously enabled with the SO_WSK_EVENT_CALLBACK socket option. For more information about enabling a socket's event callback functions, see Enabling and Disabling Event Callback Functions.

If a WSK application's WskReceiveFromEvent event callback function is enabled on a datagram socket and the application also has a pending call to the WskReceiveFrom function on the same datagram socket, then, when datagrams arrive, the pending call to the WskReceiveFrom function will take precedence over the WskReceiveFromEvent event callback function. The WSK subsystem calls the application's WskReceiveFromEvent event callback function only if there are no IRPs queued from pending calls to the WskReceiveFrom function. However, a WSK application should not assume that the WSK subsystem will not call the application's WskReceiveFromEvent event callback function for a datagram socket that has a pending call to the WskReceiveFrom function. Race conditions exist where the WSK subsystem could still call the WSK application's WskReceiveFromEvent event callback function for the socket. The only way for a WSK application to ensure that the WSK subsystem will not call the application's WskReceiveFromEvent event callback function on a datagram socket is to disable the application's WskReceiveFromEvent event callback function on the socket.

The WSK subsystem calls a WSK application's WskReceiveFromEvent event callback function at IRQL <= DISPATCH_LEVEL.

A WSK application's WskReceiveFromEvent event callback function must not wait for completion of other WSK requests in the context of WSK completion or event callback functions. The callback can initiate other WSK requests (assuming that it doesn't spend too much time at DISPATCH_LEVEL), but it must not wait for their completion even when the callback is called at IRQL = PASSIVE_LEVEL.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Windows
Header	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL