PFN_WSK_RECEIVE_FROM_EVENT callback function (wsk.h)
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 |
|---|---|
|
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. |
|
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. |
|
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.
|
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 |