Share via

3.1.1.11 Context Handles

  • Article

Sometimes operations such as querying a channels' subscription to new events for that channel can't be finished with one method call from clients. The server maintains the state information for the clients across several method calls to finish a complete workflow. The state information is server-related details and SHOULD NOT be seen by the clients. Thus, the server passes back a handle to clients and that handle maps the state information in the server. Such handles are called context handles. When clients pass back the context handle, the server knows this handle and knows the state information so that it can serve the subsequent method calls from clients.

This protocol uses the following types of context handles, and does not allow handles of different types to be interchanged:

  • PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION: This context handle is dedicated to subscription operation for the client. The client specifies a set of events to the server when setting up the subscription connection. For example, the client can ask to receive all the future events from a specified channel. The client passes that to the server and the server passes a context handle back to the client. Subsequently, the client can keep using this handle for requesting delivery of new events from the server for as long as that subscription connection is established. For this handle, the server logically needs to create an object to stand for this context handle to serve the client requests. In this protocol, this object is called the subscription object. A subscription object is a logical representation of a subscription in server memory. For detail content information on the subscription object, see the processing rules in section 3.1.4. A subscription object SHOULD contain the following information:

    1. HandleType: An integer value that describes the type of the context handle this object stands for. For the subscription object, the server SHOULD always keep this value to be the predefined type value for the type of PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION. For example, if the server decides to use 1 as the type value for PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION, it sets the HandleType to 1.

    2. Channels: An array of client subscribed channels. Each channel contains its name, log file path, and configuration properties. All the channel information can be retrieved from the corresponding channel table entry. As described in section 3.1.1.4, the channels are all registered to the server and kept in the server's channel table.

    3. IsPullType: A Boolean value to indicate pull or push subscription.

    4. Filter: The XPath query expression serving as the filter for delivering the events which meet certain criteria as specified by the filter expression. The filter is the subscription filter.

    5. Positions: An array of numeric LONGLONG values to indicate the next record ID of events for each channel that is to be delivered to the client. This array has the same size as the channels array.

      A subscription object is created by the server and cast to PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION context handle by the server before being passed to the client. The server tracks the client state inside the subscription object so that the server knows how to serve the next requests from the client.

  • PCONTEXT_HANDLE_LOG_QUERY: This context handle serves the query operation. To maintain the client state, the server SHOULD create a corresponding log query object. A log query object is a class instance that resides in the server's memory to represent the query object for the client. Inside the query object, the server SHOULD maintain the following data fields:

    1. HandleType: An integer value that describes the type of the context handle this object stands for. For the query object, the server SHOULD always set this value to the predefined type value for the type of PCONTEXT_HANDLE_LOG_QUERY. For example, if the server uses 2 as the type value for PCONTEXT_HANDLE_LOG_QUERY, it sets the HandleType to 2.

    2. The channel path: The channel name or the log file name.

    3. The query filter: The XPATH query from the client input.

    4. Position: The numeric value served as a cursor to indicate where the next return event SHOULD be. The cursor SHOULD be set to 0 initially and be updated each time the client calls the EvtRpcQuerySeek (as specified in section 3.1.4.14) or EvtRpcQueryNext (as specified in section 3.1.4.13).

      The log query object is created by the server and cast into the PCONTEXT_HANDLE_LOG_QUERY as a handle. When the client passes back the context handle, the server can cast it back to a log query object and all the internal state information is then retrieved by the server.

  • PCONTEXT_HANDLE_LOG_HANDLE: This context handle serves all the operations related to channels or logs. To do this, the server SHOULD maintain a log object mapped for this handle. The object SHOULD contain following fields:

    1. HandleType: An integer value that describes the type of the context handle this object stands for. For the query object, the server SHOULD always set this value to the predefined type value for the type of PCONTEXT_HANDLE_LOG_HANDLE. For example, if the server uses 3 as the type value for PCONTEXT_HANDLE_LOG_HANDLE, it sets the HandleType to 3.

    2. LogType: A numeric integer type value that indicates the log information object is a live channel or a backup event log.

    3. Channel: A void* pointer. When the object is a live channel, the pointer points to the channel entry in the server's channel table. When it is a backup event log, the pointer is the handle of the opened event log file.

      The object is created by the server and cast to the PCONTEXT_HANDLE_LOG_HANDLE. When the client returns the handle, the server has all the internal state information by casting it back to the log object.

  • PCONTEXT_HANDLE_PUBLISHER_METADATA: The state includes the identity of the publisher as well as the locale to be used. Sometimes the client is interested in information about a publisher that produces an event. The client sends the server the publisher's name to monitor and thus retrieves information on that publisher by issuing subsequent method calls. The server MUST open the publisher's information when the client sends the publisher's name and maintain that opened information so that subsequent methods from the client can pass back publisher information. To do this, the server maintains a publisher metadata object. The publisher metadata object is a logical representation of publisher metadata (as specified in section 3.1.1.14). The publisher metadata object SHOULD contain the following data fields:

    1. HandleType: An integer value that describes the type of the context handle this object stands for. For the query object, the server SHOULD always set this value to the predefined type value for the type of PCONTEXT_HANDLE_PUBLISHER_METADATA. For example, if the server uses 4 as the type value for PCONTEXT_HANDLE_PUBLISHER_METADATA, it sets the HandleType to 4.

    2. ResourceFile: A Unicode string for the publisher resource file name (as specified in 3.1.1.14).

    3. MessageFile: A Unicode string for the message file name (as specified in 3.1.1.14).

    4. ParameterFile: A Unicode string for the parameter file name (as specified in 3.1.1.14).

    5. Locale: An unsigned short value for the requested locale.

    6. ResourceFileHandle: The opened resource file handle so that the server can read the file.

      The publisher metadata object is created by the server and cast into the PCONTEXT_HANDLE_PUBLISHER_METADATA handle type. When the client passes the handle, the server can cast it back to the publisher metadata object.

  • PCONTEXT_HANDLE_EVENT_METADATA_ENUM: The state includes the identity of the publisher as well as the position of the enumeration. As events provider, the publisher MUST save its events in a predefined XML template (see [MSDN-ProvEvts] for information on providing events). This template is the event metadata. When clients want to enumerate the metadata of an event from a publisher, they MUST get the PCONTEXT_HANDLE_EVENT_METADATA_ENUM context handle. The server MUST maintain the client enumeration status and the publisher identity to complete this task. To maintain that state, the server maintains an event metadata object. The event metadata object is a logical representation of event metadata (as specified in section 3.1.1.14). The event metadata object SHOULD contain the following data fields:

    1. HandleType: An integer value that describes the type of the context handle this object stands for. For the query object, the server SHOULD always set this value to the predefined type value for the type of PCONTEXT_HANDLE_EVENT_METADATA_ENUM. For example, if the server uses 5 as the type value for PCONTEXT_HANDLE_EVENT_METADATA_ENUM, it sets the HandleType to 5.

    2. EventsMetaData: A memory buffer that holds the data content of the events information section of a publisher resource file (as specified in 3.1.1.14).

    3. Enumerator: A numeric integer value serving as a cursor to track the position in the event metadata section.

      The event metadata object SHOULD contain the following data fields: the events information section of a publisher resource plus a cursor (numeric value) to track the position in the event metadata section. The event metadata object is created by the server and cast into the PCONTEXT_HANDLE_EVENT_METADATA handle type. When the client passes the handle, the server can cast it back to the event metadata object.

  • PCONTEXT_HANDLE_OPERATION_CONTROL: The state includes the method calls that can be controlled by the handle. Sometimes, the client sends a method that has a long run time on the server. The client can cancel such calls that take too long to return. The client can use the PCONTEXT_HANDLE_OPERATION_CONTROL context handle to control whether the server keeps serving the call or cancels it. The server uses this context handle to maintain which operation it is serving any given client so that calls from that client are acted on. The server SHOULD maintain a control object (as specified in section 3.1.1.10) for this handle. The control object SHOULD contain the following data fields:

    1. HandleType: An integer value that describes the type of the context handle this object stands for. For the query object, the server SHOULD always set this value to be the predefined type value for the type of PCONTEXT_HANDLE_OPERATION_CONTROL. For example, if the server uses 6 as the type value for PCONTEXT_HANDLE_OPERATION_CONTROL, it sets the HandleType to 6.

    2. OperationPointer: A pointer that points to a server operation object such as a query object or a subscription object.

    3. Canceled: A Boolean value indicating whether the client has required the server to cancel the operation.

      The operation control object is created by the server and cast into the PCONTEXT_HANDLE_OPERATION_CONTROL handle type. When the client passes the handle, the server can cast it back to the control object.

These context handles are defined as pointers as specified in section 2.2.20.