3.1.4.12 EvtRpcRegisterLogQuery (Opnum 5)

  • Article

The EvtRpcRegisterLogQuery (Opnum 5) method is used to query one or more channels. It can also be used to query a specific file. Actual retrieval of events is done by subsequent calls to the EvtRpcQueryNext (section 3.1.4.13) method. 

 error_status_t EvtRpcRegisterLogQuery(
   /* [in] RPC_BINDING_HANDLE binding, {the binding handle will be generated by MIDL} */
   [in, unique, range(0, MAX_RPC_CHANNEL_PATH_LENGTH), string] 
     LPCWSTR path,
   [in, range(1, MAX_RPC_QUERY_LENGTH), string] 
     LPCWSTR query,
   [in] DWORD flags,
   [out, context_handle] PCONTEXT_HANDLE_LOG_QUERY* handle,
   [out, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL* opControl,
   [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.

path: A pointer to a string that contains a channel or file path.

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.

flags: The flags field MUST be set as follows. The first two bits indicate how the path argument MUST be interpreted. Callers MUST specify one and only one value.

Value

Meaning

EvtQueryChannelPath

0x00000001

Path specifies a channel name.

EvtQueryFilePath

0x00000002

Path specifies a file name.

These bits control the direction of the query. Callers MUST specify one and only one value.

Value

Meaning

0x00000100

Events are read from oldest to newest.

0x00000200

Events are read from newest to oldest.

The following bit can be set independently of the previously mentioned bits.

Value

Meaning

0x00001000

Specifies to return the query result set even if one or more errors result from the query.

For example, if a structured XML query specifies multiple channels, some channels are valid while others are not. A query that is used on many computers might be sent to a computer that is missing one or more channels in the query. If this bit is not set, the server MUST fail the query. If this bit is set, the query MUST succeed even if all channels are not present.

handle: A pointer to a query handle. This parameter MUST be an RPC context handle, as specified in [C706], Context Handles.

opControl: A pointer to a control handle. This parameter MUST be 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 section EvtRpcQueryChannelInfo structures, as specified in section 2.2.11.

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; in addition, the server MAY set the structure fields to nonzero values for errors unrelated to query parsing (for example, for an invalid channel name). All nonzero values MUST be treated the same. If the method succeeds, the server MUST set all the fields 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 the path parameter is non-NULL and invalid. The server checks the syntax of the query by checking whether the query string is either a valid XPath query (specified in section 2.2.15) or an XML query (specified in section 2.2.16). The server MUST interpret the path to be either a channel name or file path name, depending on the flags parameter.

The server SHOULD validate all flag values and return the error ERROR_INVALID_PARAMETER (0x00000057) if any of the following conditions occur:<17>

  • Neither EvtQueryChannelPath or EvtQueryFilePath is set.

  • Both EvtQueryChannelPath and EvtQueryFilePath are set.

  • Neither 0x00000100 nor 0x00000200 is set.

  • Both 0x00000100 and 0x00000200 are set.

  • Any flag that is not specifically defined in this list is set.

  • Both the query and the path parameters are NULL.

The server MUST fail the method if the query argument is syntactically incorrect. The server checks the syntax of the query by checking if the query string is either a valid XPath query (specified in section 2.2.15) or an XML query (specified in section 2.2.16). The server MAY not validate the semantics of the query.

For example, a client could compose a query that was intended to select all events concerning squares with more than five corners. This is an impossible situation, and the query will never return matching events. But the server has no inherent knowledge about squares; therefore, it has no way to determine that the query is invalid.

The query argument MUST be either a simple XPath (for information on the specification of the protocol's support of XPath, see section 2.2.15) or a query (for more information, see section 2.2.16). If the query is not a valid XPath (as specified in section 2.2.15) or allowed query (as specified in section 2.2.16), the server MUST fail the method with the return error ERROR_EVT_INVALID_QUERY (0x00003A99).

In the case of a query, the server MUST verify the validity of any channels or file paths specified in the query. The server SHOULD check whether the given channel is registered or the file path exists for performing the validation of channel or file path. The server SHOULD return the status of all channels found in the query via the QueryChannelInfo parameter, along with a return code that specifies the results of querying against that channel (that is, ERROR_SUCCESS (0x00000000) if the channel exists and is accessible). <18> If there is at least one invalid channel or file path in the query and the 0x00001000 bit is not set in the flags parameter, the server MUST fail the method either with the error ERROR_EVT_INVALID_CHANNEL_PATH (0x00003A98) or the error ERROR_EVT_INVALID_QUERY (0x00003A99), respectively.

Next, the server MUST verify that the caller has read access to the channel or the specified event log file and MUST fail the method if the caller does not have read access with the error code ERROR_ACCESS_DENIED (0x00000005). To perform the access check, the server SHOULD first determine the identity of the caller. Information determining the identity of the caller for the purpose of performing an access check is specified in [MS-RPCE] section 3.2.3.4.2. Then, if the client specifies a channel, the server SHOULD read the channel's access property (as specified in section 3.1.4.21) as the security descriptor string. Next, the server SHOULD be able to perform the read access check using the Access Check algorithm (as specified in [MS-DTYP] section 2.5.3.2).

If the preceding checks succeed, the server MUST attempt to create a CONTEXT_HANDLE_LOG_QUERY and return it to the caller via the handle parameter, and attempt to create a CONTEXT_HANDLE_OPERATION_CONTROL and return it in the opControl parameter. When creating the CONTEXT_HANDLE_LOG_QUERY, the server SHOULD create a log query object. The log query object is a class instance that resides in the server's memory to represent the query object for the client (as specified in section 3.1.1.11). Inside the query object, the server SHOULD set the channel path to the channel name or the event log file name the client specified, set the query filter as the XPATH query from the query parameter, and set the position to 0 initially. The position SHOULD be updated each time the client calls EvtRpcQuerySeek (as specified in section 3.1.4.14) or EvtRpcQueryNext (as specified in section 3.1.4.13). When creating the CONTEXT_HANDLE_OPERATION_CONTROL handle, the server SHOULD create an operation control object (as specified in section 3.1.1.10). The server SHOULD set the operational pointer of the control object to be the pointer of the log query object that the server creates so that it can perform control operations on that object. The server SHOULD also initially set the canceled field in the control object to false. If successful, the server MUST add the created handles to its handle table to track the issued handles. If any of the preceding checks fail, the server MUST NOT create the context handles or add them to the handle table.

The server SHOULD fail to create the two handles only in the case of memory limitation, and the server SHOULD return ERROR_OUTOFMEMORY(0x0000000E) in such case.

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