Export (0) Print
Expand All

4.7 Pull Subscription Example

In this example, the client asks to get all the events from the "Application" channel after its supplied bookmark comes through pull mode. This involves the following steps:

  1. The client registers with RPC to obtain an RPC binding handle to the service based on the endpoint information specified in section 2.1. For information on how to get the RPC binding handle, see [MSDN-BNDHNDLS].

  2. The client calls the EvtRpcRegisterRemoteSubscription method (section 3.1.4.8) to establish a subscription connection and to obtain a subscription context and operation control handles.

    error_status_t EvtRpcRegisterRemoteSubscription(
      [in] RPC_BINDING_HANDLE binding = {binding handle from step 1.},
      [in, unique, range(0, MAX_RPC_CHANNEL_NAME_LENGTH), string] LPCWSTR channelPath = L"Application",
      [in, range(1, MAX_RPC_QUERY_LENGTH), string] 
        LPCWSTR query = NULL,
      [in, unique, range(0, MAX_RPC_BOOKMARK_LENGTH), string] 
        LPCWSTR bookmarkXml = {pointer to the bookmark XML text},
      [in] DWORD flags = 0x10000003,{Pull mode and after bookmark}
      [out, context_handle] PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION* handle,
      [out, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL* control,
      [out] DWORD* queryChannelInfoSize,
      [out, size_is(, *queryChannelInfoSize), range(0, MAX_RPC_QUERY_CHANNEL_SIZE)] 
        EvtRpcQueryChannelInfo** queryChannelInfo,
      [out] RpcInfo* error
    );
    

    The bookmark XML for the example could be as follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <BookmarkList>
    <Bookmark Channel="Application" RecordId="10"/>
    </BookmarkList>
    
  3. On the server, the EvtRpcRegisterRemoteSubscription method creates the subscription object and control object. The subscription object contains one channel called "Application". Because the client requires the events after the bookmark, the server parses the bookmark XML and finds that the client requests the events whose record ID is larger than 10. Thus it sets its cursor value for the Application channel to 11. Then the server notes that the flag contains a pull mode so it sets its push mode flag to be false. For information on the control object content, see section 4.1.

    After EvtRpcRegisterRemoteSubscription creates the two objects, the server casts them to the subscription context handle and the operation control handle.

  4. After the client gets the subscription context handle, it calls the EvtRpcRemoteSubscriptionNext method (section 3.1.4.10) to fetch the events in a synchronized way.

    error_status_t EvtRpcRemoteSubscriptionNext(
      [in, context_handle] PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION handle = {the handle from step 2},
      [in] DWORD numRequestedRecords = 5,
      [in] DWORD timeOut = 1000,
      [in] DWORD flags = 0,
      [out] DWORD* numActualRecords,
      [out, size_is(,*numActualRecords), range(0, MAX_RPC_RECORD_COUNT)] DWORD** eventDataIndices,
      [out, size_is(,*numActualRecords), range(0, MAX_RPC_RECORD_COUNT)] DWORD** eventDataSizes,
      [out] DWORD* resultBufferSize,
      [out, size_is(,*resultBufferSize), range(0, MAX_RPC_BATCH_SIZE)] 
        BYTE** resultBuffer
    );
    

    Unlike the EvtRpcRemoteSubscriptionNextAsync method, this method will block the client if there are no events that match the criteria of the client's subscriber requirement. In this example, the timeOut value is 1000 (which means one second), so the client waits for one second if there are no events after the 10th record in the Application channel. Next, suppose there are events after the 10th record, the server then fills the result buffer with the available events (but not exceeding 5 because the client only demands 5 events), and then completes the call.

  5. For information on how the events in the result buffer are interpreted by the client, see section 4.1.

 
Show:
© 2014 Microsoft