Share via

3.1.4.8 EvtRpcRegisterRemoteSubscription (Opnum 0)

  • Article

The EvtRpcRegisterRemoteSubscription (Opnum 0) method is used by a client to create either a push or a pull subscription. In push subscriptions, the server calls the client when new events are ready. In pull subscriptions, the client polls the server for new events. Subscriptions can be to either a single channel and its associated log, or to multiple channels and their logs.

A client can use bookmarks to ensure a reliable subscription even if the client is not continuously connected. A client can create a bookmark locally based on the contents of an event that the client has processed. If the client disconnects and later reconnects, it can use the bookmark to pick up where it left off. For information on bookmarks, see section 2.2.14.

 error_status_t EvtRpcRegisterRemoteSubscription(
   /* [in] RPC_BINDING_HANDLE binding, {the binding handle will be generated by MIDL} */
   [in, unique, range(0, MAX_RPC_CHANNEL_NAME_LENGTH), string] 
     LPCWSTR channelPath,
   [in, range(1, MAX_RPC_QUERY_LENGTH), string] 
     LPCWSTR query,
   [in, unique, range(0, MAX_RPC_BOOKMARK_LENGTH), string] 
     LPCWSTR bookmarkXml,
   [in] DWORD flags,
   [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
 );

binding: An RPC binding handle as specified in section 2.2.21.

channelPath: A pointer to a string that contains a channel name or is a null pointer. In the case of a null pointer, the query field indicates the channels to which the subscription applies.

query: A pointer to a string that contains a query that specifies events of interest to the application. The pointer MUST be either an XPath filter, as specified in section 2.2.15, or a query as specified in section 2.2.16.

bookmarkXml: Either NULL or a pointer to a string that contains a bookmark indicating the last event that the client processed during a previous subscription. The server MUST ignore the bookmarkXML parameter unless the flags field has the bit 0x00000003 set.

flags: Flags that determine the behavior of the query.

Value

Meaning

EvtSubscribeToFutureEvents

0x00000001

Get events starting from the present time.

EvtSubscribeStartAtOldestRecord

0x00000002

Get all events from the logs, and any future events.

EvtSubscribeStartAfterBookmark

0x00000003

Get all events starting after the event indicated by the bookmark.

The following bits control other aspects of the subscription. These bits are set independently of the flags defined for the lower two bits, and independently of each other.

Value

Meaning

EvtSubscribeTolerateQueryErrors

0x00001000

The server does not fail the function as long as there is one valid channel.

EvtSubscribeStrict

0x00010000

Fail if any events are missed for reasons such as log clearing.

EvtSubscribePull

0x10000000

Subscription is going to be a pull subscription. A pull subscription requires the client to call the EvtRpcRemoteSubscriptionNext (as specified in section 3.1.4.10) method to fetch the subscribed events. If this flag is not set, the subscription is a push subscription. A push subscription requires the client to call the EvtRpcRemoteSubscriptionNextAsync (as specified in section 3.1.4.9) to receive notifications from the server when the subscribed events arrive.

handle: A context handle for the subscription. This parameter is an RPC context handle, as specified in [C706], Context Handles.

control: A context handle for the subscription. This parameter is an RPC context handle, as specified in [C706], Context Handles.

queryChannelInfoSize: A pointer to a 32-bit unsigned integer that contains the number of EvtRpcQueryChannelInfo structures returned in queryChannelInfo.

queryChannelInfo: A pointer to an array of EvtRpcQueryChannelInfo (section 2.2.11) structures that indicate the status of each channel in the subscription.

error: A pointer to an RpcInfo (section 2.2.1) structure in which to place error information in the case of a failure. The RpcInfo (section 2.2.1) structure fields MUST be set to nonzero values if the error is related to parsing the query. If the method succeeds, the server MUST set all of the values in the structure to 0.

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 fail the method if any of the following conditions occur:

  • The flags parameter specifies that the bookmarkXML parameter is used; and the bookmarkXML parameter is NULL or does not contain a valid bookmark. For more information, see section 2.2.14. The server SHOULD return ERROR_INVALID_PARAMETER (0x00000057) in this case.<10>

  • The channelPath argument specifies a channel that does not exist. The server MAY return ERROR_EVT_INVALID_CHANNEL_PATH (0x00003A98).<11>

  • The query parameter is syntactically incorrect. The server SHOULD return ERROR_EVT_INVALID_QUERY (0x00003A99) in this case. The query argument MUST be either of the following:

    • A simple XPath

      For information on the specification of the protocol's support of XPath, see section 2.2.15.

    • A query

      For more information, see section 2.2.16). The server MUST verify the validity of any channel names specified in the query, and any invalid channels MUST be returned via the QueryChannelInfo parameter.

      If there is at least one invalid channel path and the 0x00010000 bit (EvtSubscribeStrict) is set in the flags parameter, the server MUST fail the method with the error ERROR_EVT_INVALID_CHANNEL_PATH (0x00003A98).

      If the client specifies the 0x00000003 bit (EvtSubscribeStartAfterBookmark) and the 0x00010000 bit (EvtSubscribeStrict) is set in the flags parameter, the server MUST fail the method with the error ERROR_EVT_INVALID_QUERY (0x00003A99) if the events position specified by the bookmark is missing in the event channel.

      If the 0x00001000 bit (EvtSubscribeTolerateQueryErrors) is set, the function SHOULD NOT fail if the channelPath is valid although the query parameter is invalid. The method also SHOULD NOT fail if the query parameter is a structure query (as specified in section 2.2.16) that contains at least one valid channel.

      If both EvtSubscribeStrict and EvtSubscribeTolerateQueryErrors are specified in the flags parameter, the server ignores the EvtSubscribeTolerateQueryErrors and only uses the EvtSubscribeStrict flag.

      Next, the server MUST verify that the caller has read access to the files, and MUST fail the method if the caller does not have read access with the error code ERROR_ACCESS_DENIED (0x00000005).

  • If bookmarkXML is non-NULL and the EvtSubscribeStartAfterBookmark flag is set, and the log has been cleared or rolled over since the bookmark was obtained, the server MUST fail the method and return ERROR_EVT_QUERY_RESULT_STALE (0x00003AA3).

  • The server SHOULD fail the method if both the path and query parameters are NULL.<12>

The server SHOULD fail the method with the error code ERROR_INVALID_PARAMETER (0x00000057) if the flags parameter is 0 or does not contain one of the following values:

  • 0x00000001 (EvtSubscribeToFutureEvents)

  • 0x00000002 (EvtSubscribeStartAtOldestRecord)

  • 0x00000003 (EvtSubscribeStartAfterBookmark)

If the above checks all succeed, the server MUST attempt to do the following:

  • Create a CONTEXT_HANDLE_REMOTE_SUBSCRIPTION handle to the subscription.

  • Create a CONTEXT_HANDLE_OPERATION_CONTROL handle.

The server MUST set the name element to the name of the queryChannelInfo parameter to the name of the channels in question, and the status element to the status for that particular channel. For example, if the query contains the "Application" channel, the server MUST return an EvtRpcQueryChannelInfo struct with the name set to "Application"; if the query against that channel was successfully registered, the server MUST set the status element to ERROR_SUCCESS (0x00000000); if the query for that channel failed, the server MUST set the status element to an NTSTATUS error code indicating the reason for failure.

When creating the CONTEXT_HANDLE_REMOTE_SUBSCRIPTION handle, the server SHOULD create a subscription object. A subscription object is a class instance that logically stands for a subscription in the server memory as specified in section 3.1.1.11. The server SHOULD set the positions in the subscription object where the events SHOULD start in the channels based on the bookmark value if the bookmark is provided. If the bookmark is not provided, the position values are set either to be the beginning of channels if the flags contains EvtSubscribeStartAtOldestRecord, or set to be the latest position values of channels if the flags contain EvtSubscribeToFutureEvents. If the client specifies the EvtSubscribePull bit in the flags parameter, the server SHOULD set the IsPullType field in the subscription object to be true, otherwise the value SHOULD be false. The channel array in the subscription object SHOULD be set as all the client subscribed channels and the subscription filter is set to be the XPath query expression from the parameter.

When creating the CONTEXT_HANDLE_OPERATION_CONTROL handle, the server SHOULD create an operation control object. The server SHOULD set the operational pointer of the control object to be the pointer of the subscription object that the server creates so that it can perform control operations on that object. The server SHOULD also set the canceled field in the control object initially to false. If the client waits too long for the subscription, it can use the EvtRpcCancel method (as specified in section 3.1.4.34) to cancel the subscription. Since the operation control object contains the subscription pointer, it can request the subscription to stop on the server side.

The server SHOULD only fail the creation of handles in the case of not enough memory and return ERROR_OUTOFMEMORY (0x0000000E). The server SHOULD add the newly created handles to its handle table in order to track them.

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