<div class="content"><p> </p><p>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.</p><p>A client can use <span><a href="726c3b3b-eaa6-48f2-a592-519459a4eeb1" data-linktype="relative-path">bookmarks</a></span> 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.</p><dl>
<dd>
<div><pre> 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
 );
</pre></div>
</dd></dl><p><b>binding: </b>An RPC binding handle as specified in
section <span><a href="1285c318-9f8c-4c6a-a963-7999557bf8d8" data-linktype="relative-path">2.2.21</a></span>.</p><p><b>channelPath: </b>A pointer to a string that
contains a channel name or is a null pointer. In the case of a null pointer,
the <i>query</i> field indicates the channels to which the subscription
applies.</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 <span><a href="b9c96c9d-6e19-4815-b05d-885360019dda" data-linktype="relative-path">2.2.15</a></span>, or a query
as specified in section <span><a href="89a53696-045d-4616-9c13-07550075d2e5" data-linktype="relative-path">2.2.16</a></span>.</p><p><b>bookmarkXml: </b>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.</p><p><b>flags: </b>Flags that determine the behavior of
the query.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>
  <p>EvtSubscribeToFutureEvents</p>
  <p>0x00000001</p>
  </td>
  <td>
  <p>Get events starting from the present time.</p>
  </td>
 </tr><tr>
  <td>
  <p>EvtSubscribeStartAtOldestRecord</p>
  <p>0x00000002</p>
  </td>
  <td>
  <p>Get all events from the logs, and any future events.</p>
  </td>
 </tr><tr>
  <td>
  <p>EvtSubscribeStartAfterBookmark</p>
  <p>0x00000003</p>
  </td>
  <td>
  <p>Get all events starting after the event indicated by
  the bookmark.</p>
  </td>
 </tr></tbody></table>
</dd>
<dd>
<p>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.</p>
</dd>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>
  <p>EvtSubscribeTolerateQueryErrors</p>
  <p>0x00001000</p>
  </td>
  <td>
  <p>The server does not fail the function as long as there
  is one valid channel.</p>
  </td>
 </tr><tr>
  <td>
  <p>EvtSubscribeStrict</p>
  <p>0x00010000</p>
  </td>
  <td>
  <p>Fail if any events are missed for reasons such as log
  clearing.</p>
  </td>
 </tr><tr>
  <td>
  <p>EvtSubscribePull</p>
  <p>0x10000000</p>
  </td>
  <td>
  <p>Subscription is going to be a pull subscription. A
  pull subscription requires the client to call the <b>EvtRpcRemoteSubscriptionNext</b>
  (as specified in section <span><a href="cd4c258c-5a2c-4ba8-bce3-37eefaa416e7" data-linktype="relative-path">3.1.4.10</a></span>) 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 <b>EvtRpcRemoteSubscriptionNextAsync</b>
  (as specified in section <span><a href="e567bf31-913a-4369-846d-a38eb3f97aa0" data-linktype="relative-path">3.1.4.9</a></span>) to
  receive notifications from the server when the subscribed events arrive.</p>
  </td>
 </tr></tbody></table>
</dd></dl><p><b>handle: </b>A context handle for the subscription.
This parameter is an <span><a href="fda52b23-608b-444e-a979-6b62a00e8f48#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a></span> context handle,
as specified in <span><a href="https://go.microsoft.com/fwlink/?LinkId=89824" data-linktype="external">[C706]</a></span>, Context
Handles.</p><p><b>control: </b>A context handle for the
subscription. This parameter is 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 <span><a href="23027ebf-46f0-4080-86ae-18c74b6678c8" data-linktype="relative-path">EvtRpcQueryChannelInfo</a></span>
structures returned in <i>queryChannelInfo</i>.</p><p><b>queryChannelInfo: </b>A pointer to an array of
EvtRpcQueryChannelInfo (section 2.2.11) structures that indicate the
status of each channel in the subscription. </p><p><b>error: </b>A pointer to an <span><a href="94a5d4d1-0f80-4af3-b7c6-d61a6aa60b7b" data-linktype="relative-path">RpcInfo (section 2.2.1)</a></span>
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.</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 <span><a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a></span>.</p><p>In response to this request from the client, the server MUST
fail the method if any of the following conditions occur:</p><ul><li><p><span><span> 
</span></span>The <i>flags</i> parameter specifies that the <i>bookmarkXML</i>
parameter is used; and the <i>bookmarkXML</i> 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.<a id="Appendix_A_Target_10"></a><a aria-label="Product behavior note 10" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_10" data-linktype="relative-path">&lt;10&gt;</a></p>
</li><li><p><span><span> 
</span></span>The <i>channelPath</i> argument specifies a channel that does not
exist. The server MAY return ERROR_EVT_INVALID_CHANNEL_PATH (0x00003A98).<a id="Appendix_A_Target_11"></a><a aria-label="Product behavior note 11" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_11" data-linktype="relative-path">&lt;11&gt;</a></p>
</li><li><p><span><span> 
</span></span>The <i>query</i> parameter is syntactically incorrect. The server
SHOULD return ERROR_EVT_INVALID_QUERY (0x00003A99) in this case. The <i>query</i>
argument MUST be either of the following: </p>
<ul><li><p><span><span>  </span></span>A
simple XPath</p>
<p>For information on the
specification of the protocol&#39;s support of XPath, see section 2.2.15.</p>
</li><li><p><span><span>  </span></span>A
query</p>
<p>For more information, see
section 2.2.16). The server MUST verify the validity of any <span><a href="c14b1cf5-ec9b-47c8-9b8a-9cc08c80fbbc" data-linktype="relative-path">channel
names</a></span> specified in the query, and any invalid channels MUST be
returned via the <i>QueryChannelInfo</i> parameter.</p>
<p>If there is at least one
invalid channel path and the 0x00010000 bit (<b>EvtSubscribeStrict</b>) is set
in the <i>flags</i> parameter, the server MUST fail the method with the error
ERROR_EVT_INVALID_CHANNEL_PATH (0x00003A98).</p>
<p>If the client specifies
the 0x00000003 bit (<b>EvtSubscribeStartAfterBookmark</b>) and the 0x00010000
bit (<b>EvtSubscribeStrict</b>) is set in the flags parameter, the server MUST
fail the method with the error <b>ERROR_EVT_INVALID_QUERY</b> (0x00003A99) if
the events position specified by the bookmark is missing in the event channel.</p>
<p>If the 0x00001000 bit (<b>EvtSubscribeTolerateQueryErrors</b>)
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.</p>
<p>If both <b>EvtSubscribeStrict</b>
and <b>EvtSubscribeTolerateQueryErrors</b> are specified in the flags
parameter, the server ignores the <b>EvtSubscribeTolerateQueryErrors</b> and
only uses the <b>EvtSubscribeStrict</b> flag.</p>
<p>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).</p>
</li></ul></li><li><p><span><span> 
</span></span>If <i>bookmarkXML</i> is non-NULL and the <b>EvtSubscribeStartAfterBookmark</b>
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).</p>
</li><li><p><span><span> 
</span></span>The server SHOULD fail the method if both the path and query
parameters are NULL.<a id="Appendix_A_Target_12"></a><a aria-label="Product behavior note 12" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_12" data-linktype="relative-path">&lt;12&gt;</a></p>
</li></ul><p>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:</p><ul><li><p><span><span> 
</span></span>0x00000001 (<b>EvtSubscribeToFutureEvents</b>)</p>
</li><li><p><span><span> 
</span></span>0x00000002 (<b>EvtSubscribeStartAtOldestRecord</b>)</p>
</li><li><p><span><span> 
</span></span>0x00000003 (<b>EvtSubscribeStartAfterBookmark</b>)</p>
</li></ul><p>If the above checks all succeed, the server MUST attempt to
do the following:</p><ul><li><p><span><span> 
</span></span>Create a CONTEXT_HANDLE_REMOTE_SUBSCRIPTION handle to the subscription.</p>
</li><li><p><span><span> 
</span></span>Create a CONTEXT_HANDLE_OPERATION_CONTROL handle.</p>
</li></ul><p>The server MUST set the name element to the name of the <i>queryChannelInfo</i>
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
&#34;Application&#34; channel, the server MUST return an
EvtRpcQueryChannelInfo struct with the name set to &#34;Application&#34;; 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 <span><a href="../ms-erref/87fba13e-bf06-450e-83b1-9241dc81e781" data-linktype="relative-path">NTSTATUS</a></span>
error code indicating the reason for failure.</p><p>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 <span><a href="2a5dd9ce-aef8-4a03-b42d-be9393a5a5e8" data-linktype="relative-path">3.1.1.11</a></span>. 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 <b>EvtSubscribeStartAtOldestRecord</b>,
or set to be the latest position values of channels if the flags contain <b>EvtSubscribeToFutureEvents</b>.
If the client specifies the EvtSubscribePull bit in the <i>flags</i> 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
<span><a href="fda52b23-608b-444e-a979-6b62a00e8f48#gt_d74bcc19-5383-49d9-acfc-c79518cd2fbf" data-linktype="relative-path">subscription
filter</a></span> is set to be the XPath query expression from the parameter. </p><p>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 <span><a href="66f25e52-a600-4cb4-9182-b9aa8f50d38e" data-linktype="relative-path">EvtRpcCancel</a></span> 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.</p><p>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.</p><p>The server MUST return a value that indicates success or
failure for this operation.</p></div>