Share via

3.1.4.14 EvtRpcQuerySeek (Opnum 12)

  • Article

The EvtRpcQuerySeek (Opnum 12) method is used by a client to move a query cursor within a result set. 

 error_status_t EvtRpcQuerySeek(
   [in, context_handle] PCONTEXT_HANDLE_LOG_QUERY logQuery,
   [in] __int64 pos,
   [in, unique, range(0, MAX_RPC_BOOKMARK_LENGTH), string] 
     LPCWSTR bookmarkXml,
   [in] DWORD timeOut,
   [in] DWORD flags,
   [out] RpcInfo* error
 );

logQuery: A handle to an event log. This parameter is an RPC context handle, as specified in [C706], Context Handles.

pos: The number of records in the result set to move by. If the number is positive, the movement is the same as the direction of the query that was specified in the EvtRpcRegisterLogQuery (section 3.1.4.12) method call that was used to obtain the handle specified by the logQuery parameter. If the number is negative, the movement is in the opposite direction of the query.

bookmarkXml: A pointer to a string that contains a bookmark.

timeOut: A 32-bit unsigned integer that MUST be set to 0x00000000 when sent and MAY be ignored on receipt.

flags: This MUST be set as follows: this 32-bit unsigned integer contains flags that describe the absolute position from which EvtRpcQuerySeek (Opnum 12) starts its seek. The origin flags (the first four flags that follow) are mutually exclusive; however, the last flag can be set independently. The pos parameter specifies the offset used in the definitions of these flags.

Value

Meaning

EvtSeekRelativeToFirst

0x00000001

The offset is relative to the first entry in the result set and SHOULD be nonnegative. Therefore, if an offset of 0 is specified, the cursor is moved to the first entry in the result set.

EvtSeekRelativeToLast

0x00000002

The offset is relative to the last entry in the result set and SHOULD be nonpositive. Therefore, if an offset of 0 is specified, the cursor is moved to the last entry in the result set.

EvtSeekRelativeToCurrent

0x00000003

The offset is relative to the current cursor location. If an offset of 0 is specified, the cursor is not to be moved. A positive or negative number can be used in this case to move the cursor to any other location.

EvtSeekRelativeToBookmark

0x00000004

The offset is relative to the bookmark location. If an offset of 0 is specified, the cursor is positioned at the bookmark. A positive or negative number can be used in this case to move the cursor to any other location. The server MUST fail the operation if the bookmarkXml parameter does not specify a valid position in the log.

The presence of the EvtSeekStrict flag SHOULD influence the behavior of this flag, as specified below.

EvtSeekStrict

0x00010000

If this is set, the query fails if the seek cannot go to the record indicated by the other flags/parameters. If not set, the seek uses a best effort.

For example, if 99 records remain in the result set and the pos parameter specifies 100 with the EvtSeekRelativeToCurrent flag set, the 99th record is selected.

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 structure fields MUST be set to nonzero values if the error is related to parsing the query. In addition, the server MAY set the structure fields to nonzero values for errors unrelated to query parsing. All nonzero values MUST be treated the same by the client.

If the method succeeds, the server MUST set all the values in the structure to zero.

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.13. The server SHOULD fail the method with the return code ERROR_INVALID_PARAMETER (0x00000057) if the handle is invalid.

The server SHOULD<22> validate that the sign of the pos parameter makes sense for the search direction. That is, the server returns ERROR_INVALID_PARAMETER (0x00000057) if a negative pos value is specified along with the EvtSeekRelativeToFirst flag and if a positive pos value is specified along with the EvtSeekRelativeToLast flag.

The server SHOULD validate that the bookmarkXML parameter has the correct syntax for the book mark. If it is not correct, the server SHOULD return ERROR_INVALID_PARAMETER (0x00000057).

The server MUST validate that one and only one of the mutually exclusive flags are specified and return ERROR_INVALID_PARAMETER (0x00000057) if this condition is not met. The mutually exclusive flags are:

  • EvtSeekRelativeToFirst

  • EvtSeekRelativeToLast

  • EvtSeekRelativeToCurrent

  • EvtSeekRelativeToBookmark

If validation succeeds, the server uses the address of the logQuery context handle as a pointer to the log query object, with implementation-specific typecasting as necessary. Then the following operations SHOULD be done:

  1. Set the position value in the log query object to the initial value based on the flags.

    1. EvtSeekRelativeToFirst: Position set to 0.

    2. EvtSeekRelativeToLast: Position set to the number of records in the channel.

    3. EvtSeekRelativeToCurrent: Position unchanged.

    4. EvtSeekRelativeToBookmark: Read the event record Id from the bookmark XML, read every event from the beginning and try to find the same event record Id as specified in the bookmark XML. The position is the value of how many records the server has read before finding the same event record Ids.

  2. When pos parameter is bigger than 0, the server reads one event record from its current position and increments the position value by 1. With the event record, the server tries to match the query filter (the XPath expression). If the event matches the filter requirement, the server decreases the pos value by 1. If the event does not match, the pos value is kept the same. Then the server reads the next record, and repeats the process until the pos value becomes 0. Then the server returns to the client indicating the seek operation is finished.

  3. When pos parameter is a negative value, the server reads the event record in reverse order. It reads the previous event record from its current position and decrements the position value by 1 each time it reads a previous record. With the record it reads, it tries to match the query filter (the XPath expression). If the event matches the filter requirement, the server increases the pos value by 1. If the event does not match, the pos value is kept the same. Next, the server reads the next previous record. This process is repeated until the pos value becomes 0. Then the server returns the value to the client indicating that the seek operation is finished.

If the client specifies the EvtSeekRelativeToBookmark flag and the server can't find the event record Id that matches the record Id in the bookmark XML, the server SHOULD return ERROR_NOT_FOUND (0x00000490) if the client specifies the EvtSeekStrict at the same time. Otherwise, the server tries to set the position to the nearest record matching the record Id specified in the bookmark. For example, if the record Id in the bookmark is 1000, and the event records in the log only has 999, 1002, 1003 as the record Ids, the server SHOULD stops at the event record whose record Id is 999.

In the previous server mutually exclusive flags validation, steps 2 or 3, if the server reaches either the beginning or the end of the event log file before the pos parameter reaches 0, the server SHOULD check if the client has specified the flag EvtSeekSrict. If so, the server will not return error. Otherwise, the server SHOULD return ERROR_NOT_FOUND (0x00000490).

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