3.1.4.2.143 ApiGetNotifyAsync (Opnum 147)

(Protocol Version 3) The ApiGetNotifyAsync method is an asynchronous RPC method that SHOULD<130> be used instead of ApiGetNotify to instruct the server to return the next set of queued events corresponding to a particular context handle. The server MUST NOT complete this method until an indication has been queued to the port or the port has been closed through a separate call to the ApiUnblockGetNotifyCall or ApiCloseNotify method.

 error_status_t ApiGetNotifyAsync(
   [in] HNOTIFY_RPC hNotify,
   [out, size_is(,*dwNumNotifications)] 
     PNOTIFICATION_DATA_ASYNC_RPC* Notifications,
   [out] DWORD *dwNumNotifications
 );

hNotify: An HNOTIFY_RPC (section 2.2.1.6) context handle that was obtained in a previous ApiCreateNotify (section 3.1.4.2.56) method call.

Notifications: A pointer to an array of one or more NOTIFICATION_DATA_ASYNC_RPC (section 2.2.3.30) structures corresponding to the next notification events that have been generated on the specified notification port, but have not yet been retrieved through previous calls to ApiGetNotifyAsync or ApiGetNotify.

dwNumNotifications: A pointer to a DWORD that contains the count of NOTIFICATION_DATA_ASYNC_RPC structures.

Return Values: This method MUST return one of the following values.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The method completed successfully.
0x00000006 ERROR_INVALID_HANDLE	The data that is pointed to by the hNotify parameter does not represent a valid HNOTIFY_RPC context handle.
0x00000103 ERROR_NO_MORE_ITEMS	The notification port represented by the hNotify parameter has been closed.
0x00000001 ERROR_INVALID_FUNCTION	Either the ApiUnblockGetNotifyCall (section 3.1.4.2.107) method or the ApiCloseNotify (section 3.1.4.2.57) method has been called in another thread. The client SHOULD terminate the notification thread.

For any other condition, the server returns a value that is not one of the values listed in the preceding table. The client MUST treat all such values identically, with the exception of errors specified in section 3.2.4.6, which are recoverable and for which the client SHOULD initiate the reconnect procedure.