Share via

3.1.4.11 EvtRpcRemoteSubscriptionWaitAsync (Opnum 3)

  • Article

Pull subscriptions are subscriptions in which the client requests records. The requests can be done by using a polling mechanism. The EvtRpcRemoteSubscriptionWaitAsync (Opnum 3) method can be used to enable the client to only poll when results are likely, and is typically used in conjunction with the EvtRpcRemoteSubscriptionNext (Opnum 2) (section 3.1.4.10) method, which is a blocking call; so this asynchronous method is used to provide a way for the caller to not have to block or continuously poll the server.

 error_status_t EvtRpcRemoteSubscriptionWaitAsync(
   [in, context_handle] PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION handle
 );

handle: A handle to a subscription, as obtained from the EvtRpcRegisterRemoteSubscription (section 3.1.4.8) method. This parameter MUST be an RPC context handle, as specified in [C706] Context Handles.

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success; otherwise, it MUST return an implementation-specific nonzero value as specified in [MS-ERREF].

In response to this request from the client, the server MUST first validate the handle. For processing rules for handle validation, see the remarks in section 3.1.4.9. The server SHOULD fail the method with the return code ERROR_INVALID_PARAMETER (0x00000057) if it has no state for the handle.<16>

After the server validates the handle, it casts the handle value to the subscription object. The server then MUST check whether the subscription object is a push subscription. Because the subscription object contains the type of subscription, the server checks its type and SHOULD fail the method if it is not a push type subscription with the error ERROR_INVALID_OPERATION(0x000010DD).

If the preceding check is successful, the server MUST determine whether there are any events the client has not received that pass the subscription filters. The subscription object contains the information of the last event since its last delivery to the client. If there is no new event from the last time the server returned events to the client until the current moment, the server does not complete the call and SHOULD return anything to the client. If there are new events coming in, the server applies the subscription filters and if those events pass the filters, the server SHOULD call RpcAyncCompleteCall (see [MSDN-RpcAsyncCompleteCall]) to complete the async call so that the client will receive notification. Then the client will use EvtRpcRemoteSubscriptionNext (as specified in section 3.1.4.10) to get those new events from the server. The subscription filters are the XPath queries that the client specifies in the query parameter in the EvtRpcRegisterRemoteSubscription method (as specified in section 3.1.4.8). For information on how the server applies the filter, see [MSDN-CONSUMEVTS]. If there are no events meeting that criteria, the server MUST NOT complete this operation.

The server SHOULD be notified by the underlying network that the connection is lost from the client if the client abnormally terminates the connection. The server abandons its operation for the client in such a case. The server SHOULD release the subscription object it creates and free all associated resources. The associated resources are described in EvtRpcRegisterRemoteSubscription (Opnum 0) (section 3.1.4.8).

The server MUST return a value indicating success or failure for this operation.