LPFN_RIONOTIFY callback function (mswsock.h)

The RIONotify function registers the method to use for notification behavior with an I/O completion queue for use with the Winsock registered I/O extensions.

Syntax

LPFN_RIONOTIFY LpfnRionotify;

INT LpfnRionotify(
  RIO_CQ CQ
)
{...}

Parameters

CQ

A descriptor that identifies an I/O completion queue.

Return value

If no error occurs, the RIONotify function returns ERROR_SUCCESS. Otherwise, the function failed and a specific error code is returned.

Return code	Description
WSAEINVAL	An invalid parameter was passed to the function. This error is returned if invalid completion queue is passed in the CQ parameter (RIO_INVALID_CQ, for example). This error can also be returned when an internal error occurs.
WSAEALREADY	An operation was attempted on a non-blocking socket that already had an operation in progress. This error is returned if a previous RIONotify request has not yet completed.

Remarks

The RIONotify function registers the method to be used for notification behavior for sending or receiving network data with the Winsock registered I/O extensions.

The RIONotify function is the mechanism by which an application finds out that requests are completed and are awaiting a call to the RIODequeueCompletion function. The RIONotify function sets the method to be used for notification behavior when an I/O completion queue is not empty and contains the completion of a result.

The notification behavior for a completion queue is set when the RIO_CQ is created. The RIO_NOTIFICATION_COMPLETION structure is passed to the RIOCreateCompletionQueue function when a RIO_CQ is created.

For a completion queue that uses an event, the Type member of the RIO_NOTIFICATION_COMPLETION structure is set to RIO_EVENT_COMPLETION. The Event.EventHandle member should contain the handle for an event created by the WSACreateEvent or CreateEvent function. To receive the RIONotify completion, the application should wait on the specified event handle using WSAWaitForMultipleEvents or a similar wait routine. If the application plans to reset and reuse the event, the application can reduce overhead by setting the Event.NotifyReset member to a non-zero value. This causes the event to be automatically reset by the RIONotify function when the notification occurs. This mitigates the need to call the WSAResetEvent function to reset the event between calls to the RIONotify function.

When the RIONotify function is called used event completion and the specified completion queue is already not empty, the event is set either synchronously or asynchronously. In both cases, additional entries do not need to enter the completion queue before the event is set. Until the completion queue contains the completion of a request that did not have the RIO_MSG_DONT_NOTIFY flag set, the completion queue is considered empty for the purposes of the RIONotify function and the event is not set. Any completed requests can still be retrieved using the RIODequeueCompletion function. When the event is set, the application typically calls the RIODequeueCompletion function to dequeue the completed send and receive requests.

For a completion queue that uses an I/O completion port, the Type member of the RIO_NOTIFICATION_COMPLETION structure is set to RIO_IOCP_COMPLETION. The Iocp.IocpHandle member should contain the handle for an I/O completion port created by the CreateIoCompletionPort function. To receive the RIONotify completion, the application should call the GetQueuedCompletionStatus or GetQueuedCompletionStatusEx function. The application should provide a dedicated OVERLAPPED object for the completion queue, and it may also use the Iocp.CompletionKey member to distinguish RIONotify requests on the completion queue from other I/O completions including RIONotify completions for other completion queues.

An application using thread pools can use thread pool wait objects to get RIONotify completions via its thread pool. In that case, the call to the SetThreadpoolWait function should immediately follow the call to RIONotify. If the SetThreadpoolWait function is called before RIONotify and the application relies on RIONotify to clear the event object, this may result in spurious executions of the wait object callback.

Note

The function pointer to the RIONotify function must be obtained at run time by making a call to the WSAIoctl function with the SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode specified. The input buffer passed to the WSAIoctl function must contain WSAID_MULTIPLE_RIO, a globally unique identifier (GUID) whose value identifies the Winsock registered I/O extension functions. On success, the output returned by the WSAIoctl function contains a pointer to the RIO_EXTENSION_FUNCTION_TABLE structure that contains pointers to the Winsock registered I/O extension functions. The SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL is defined in the Ws2def.h header file. The WSAID_MULTIPLE_RIO GUID is defined in the Mswsock.h header file.

 

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Thread Safety

If multiple threads attempt to access the same RIO_CQ using the RIODequeueCompletion function, access must be coordinated by a critical section, slim reader writer lock , or similar mutual exclusion mechanism. If the completion queues are not shared, mutual exclusion is not required.

Requirements

Requirement	Value
Header	mswsock.h