<div class="content" name="EvtRpcRegisterLogQuery" uuid="c7a37af2-fb11-4c26-b3af-694183bfdd68"><p>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 <a href="f659a847-abbb-4f4f-b173-42b18565cebd" data-linktype="relative-path">EvtRpcQueryNext (section 3.1.4.13)</a>
method. </p><dl>
<dd>
<div><pre> 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
 );
</pre></div>
</dd></dl><p><b>binding: </b>An RPC binding handle as specified in
section <a href="1285c318-9f8c-4c6a-a963-7999557bf8d8" data-linktype="relative-path">2.2.21</a>.</p><p><b>path: </b>A pointer to a string that contains a
channel or file path. </p><p><b>query: </b>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 <a href="b9c96c9d-6e19-4815-b05d-885360019dda" data-linktype="relative-path">2.2.15</a>, or a query, as
specified in section <a href="89a53696-045d-4616-9c13-07550075d2e5" data-linktype="relative-path">2.2.16</a>.</p><p><b>flags: </b>The flags field MUST be set as follows.
The first two bits indicate how the <i>path</i> argument MUST be interpreted.
Callers MUST specify one and only one value.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>EvtQueryChannelPath 0x00000001</td>
  <td>Path specifies a channel name.</td>
 </tr><tr>
  <td>EvtQueryFilePath 0x00000002</td>
  <td>Path specifies a file name.</td>
 </tr></tbody></table>
</dd>
<dd>
<p>These bits control the direction of the query.
Callers MUST specify one and only one value. </p>
</dd>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000100</td>
  <td>Events are read from oldest to newest.</td>
 </tr><tr>
  <td>0x00000200</td>
  <td>Events are read from newest to oldest.</td>
 </tr></tbody></table>
</dd>
<dd>
<p>The following bit can be set independently of the
previously mentioned bits.</p>
</dd>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00001000</td>
  <td>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.</td>
 </tr></tbody></table>
</dd></dl><p><b>handle: </b>A pointer to a query handle. This
parameter MUST be an <a href="fda52b23-608b-444e-a979-6b62a00e8f48#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a>
context handle, as specified in <a href="https://go.microsoft.com/fwlink/?LinkId=89824" data-linktype="external">[C706]</a>, Context
Handles. </p><p><b>opControl: </b>A pointer to a control handle. This
parameter MUST be an RPC context handle, as specified in [C706], Context
Handles.</p><p><b>queryChannelInfoSize: </b>A pointer to a 32-bit
unsigned integer that contains the number of <a href="23027ebf-46f0-4080-86ae-18c74b6678c8" data-linktype="relative-path">EvtRpcQueryChannelInfo</a>
structures returned in <i>queryChannelInfo</i>.</p><p><b>queryChannelInfo: </b>A pointer to an array of
section EvtRpcQueryChannelInfo structures, as specified in section 2.2.11. </p><p><b>error: </b>A pointer to an <a href="94a5d4d1-0f80-4af3-b7c6-d61a6aa60b7b" data-linktype="relative-path">RpcInfo (section 2.2.1)</a>
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.</p><p><b>Return Values: </b>The method MUST return ERROR_SUCCESS
(0x00000000) on success; otherwise, it MUST return an implementation-specific
nonzero value as specified in <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>.</p><p>In response to this request from the client, the server MUST
fail the method if the <i>path</i> 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 <i>path</i> to be
either a channel name or file path name, depending on the <i>flags</i>
parameter. </p><p>The server SHOULD validate all flag values and return the
error ERROR_INVALID_PARAMETER (0x00000057) if any of the following conditions
occur:<a id="Appendix_A_Target_17"></a><a aria-label="Product behavior note 17" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_17" data-linktype="relative-path">&lt;17&gt;</a></p><ul><li><p><span><span> 
</span></span>Neither EvtQueryChannelPath or EvtQueryFilePath is set.</p>
</li><li><p><span><span> 
</span></span>Both EvtQueryChannelPath and EvtQueryFilePath are set.</p>
</li><li><p><span><span> 
</span></span>Neither 0x00000100 nor 0x00000200 is set.</p>
</li><li><p><span><span> 
</span></span>Both 0x00000100 and 0x00000200 are set.</p>
</li><li><p><span><span> 
</span></span>Any flag that is not specifically defined in this list is set.</p>
</li><li><p><span><span> 
</span></span>Both the query and the path parameters are NULL.</p>
</li></ul><p>The server MUST fail the method if the <i>query</i> 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. </p><p>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.</p><p>The <i>query</i> argument MUST be either a simple XPath (for
information on the specification of the protocol&#39;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).</p><p>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 <i>QueryChannelInfo</i> 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).
<a id="Appendix_A_Target_18"></a><a aria-label="Product behavior note 18" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_18" data-linktype="relative-path">&lt;18&gt;</a> If there is at least one
invalid channel or file path in the query and the 0x00001000 bit is not set in
the <i>flags</i> 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.</p><p>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 <a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a>
section <a href="../ms-rpce/326c9de1-4602-4d78-848d-8b4e11e6ed80" data-linktype="relative-path">3.2.3.4.2</a>.
Then, if the client specifies a channel, the server SHOULD read the channel&#39;s
access property (as specified in section <a href="f5ae9a61-6f5e-4751-965e-394349c7d950" data-linktype="relative-path">3.1.4.21</a>) 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 <a href="../ms-dtyp/cca27429-5689-4a16-b2b4-9325d93e4ba2" data-linktype="relative-path">[MS-DTYP]</a>
section <a href="../ms-dtyp/4f1bbcbb-814a-4c70-a11e-2a5b8779a6f9" data-linktype="relative-path">2.5.3.2</a>).
</p><p>If the preceding checks succeed, the server MUST attempt to
create a <a href="ef007e79-0549-446f-a928-379f47d57cfd" data-linktype="relative-path">CONTEXT_HANDLE_LOG_QUERY</a>
and return it to the caller via the <i>handle</i> parameter, and attempt to
create a CONTEXT_HANDLE_OPERATION_CONTROL and return it in the <i>opControl</i>
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&#39;s memory to represent the query object for the client (as specified
in section <a href="2a5dd9ce-aef8-4a03-b42d-be9393a5a5e8" data-linktype="relative-path">3.1.1.11</a>).
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 <b>EvtRpcQuerySeek</b>
(as specified in section <a href="940e1f4c-89cc-49f4-9cee-f73e2001e000" data-linktype="relative-path">3.1.4.14</a>)
or <b>EvtRpcQueryNext</b> (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 <a href="cd433336-1e83-4d8b-ab45-1c748d835312" data-linktype="relative-path">3.1.1.10</a>). 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.</p><p>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.</p><p>The server MUST return a value indicating success or failure
for this operation.</p></div>