<div class="content" name="EvtRpcRemoteSubscriptionNextAsync" uuid="e567bf31-913a-4369-846d-a38eb3f97aa0"><p>The EvtRpcRemoteSubscriptionNextAsync (Opnum 1) method is
used by a client to request asynchronous delivery of events that are delivered
to a subscription.</p><dl>
<dd>
<div><pre> error_status_t EvtRpcRemoteSubscriptionNextAsync(
   [in, context_handle] PCONTEXT_HANDLE_REMOTE_SUBSCRIPTION handle,
   [in] DWORD numRequestedRecords,
   [in] DWORD flags,
   [out] DWORD* numActualRecords,
   [out, size_is(,*numActualRecords), range(0, MAX_RPC_RECORD_COUNT)] 
     DWORD** eventDataIndices,
   [out, size_is(,*numActualRecords), range(0, MAX_RPC_RECORD_COUNT)] 
     DWORD** eventDataSizes,
   [out] DWORD* resultBufferSize,
   [out, size_is(, *resultBufferSize), range(0, MAX_RPC_BATCH_SIZE)] 
     BYTE** resultBuffer
 );
</pre></div>
</dd></dl><p><b>handle: </b>A handle to the subscription. This
parameter is 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>numRequestedRecords: </b>A 32-bit unsigned integer
that contains the number of events to return.</p><p><b>flags: </b>A 32-bit unsigned integer that MUST be
set to zero when sent and MAY be ignored on receipt.<a id="Appendix_A_Target_13"></a><a aria-label="Product behavior note 13" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_13" data-linktype="relative-path">&lt;13&gt;</a></p><p><b>numActualRecords: </b>A pointer to a 32-bit
unsigned integer that contains the value that, on success, MUST be set to the
number of events retrieved. This might be used, for example, if the method
times out without receiving the full number of events specified in <i>numRequestedRecords</i>.</p><p><b>eventDataIndices: </b>A pointer to an array of
32-bit unsigned integers that contain the offsets for the event. An event&#39;s
offset is its position relative to the start of <i>resultBuffer</i>.</p><p><b>eventDataSizes: </b>A pointer to an array of
32-bit unsigned integers that contain the event sizes in bytes.</p><p><b>resultBufferSize: </b>A pointer to a 32-bit
unsigned integer that contains the number of bytes of data returned in <i>resultBuffer</i>.</p><p><b>resultBuffer: </b>A pointer to a byte-array that
contains the <a href="fda52b23-608b-444e-a979-6b62a00e8f48#gt_c8a27238-8ccc-442b-9604-75f74d3e6b3d" data-linktype="relative-path">result set</a>
of one or more events. The events MUST be in binary XML format, as specified in
section <a href="762528ba-f36a-4d17-ba2b-0f0244a45f2f" data-linktype="relative-path">2.2.17</a>.</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
first validate the handle. The server SHOULD fail the operation if the handle
is not valid. The server SHOULD save the handle value it creates and returns to
the client via the handle parameter in the <b>EvtRpcRegisterRemoteSubscription</b>
method (as specified in section <a href="4364e323-0885-4e2f-9d55-70cf57cd6b95" data-linktype="relative-path">3.1.4.8</a>) in its handle
table (as specified in section <a href="32102cb3-ea77-4171-bd1a-33c8c4d882aa" data-linktype="relative-path">3.1.1.12</a>) and compare it
with the handle passed here to perform the check.<a id="Appendix_A_Target_14"></a><a aria-label="Product behavior note 14" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_14" data-linktype="relative-path">&lt;14&gt;</a> The
server MUST return ERROR_INVALID_PARAMETER (0x00000057) if the handle is invalid.</p><p>After the server validates the handle, it casts the handle
value to the subscription object. The server then MUST check whether the
subscription object is a push subscription. Since the subscription object
contains the type of subscription, the server checks its type and SHOULD fail
the method if it is not a push type subscription with the error
ERROR_INVALID_OPERATION(0x000010DD).</p><p>If the preceding check succeeds, the server MUST determine
whether there are any events the client has not received that pass the <a href="fda52b23-608b-444e-a979-6b62a00e8f48#gt_d74bcc19-5383-49d9-acfc-c79518cd2fbf" data-linktype="relative-path">subscription filters</a>. The
subscription filters are the XPath queries that the client specifies in the
query parameter in the <b>EvtRpcRegisterRemoteSubscription</b> method (as
specified in section 3.1.4.8). For information on how the server applies the
filter, see <a href="https://go.microsoft.com/fwlink/?LinkId=207352" data-linktype="external">[MSDN-CONSUMEVTS]</a>.
The server MUST wait until there is at least one event the client has not
received before completing this call. Once there is at least one event, the
server MUST return the event or events, and then update its subscription object
state to keep track of what events have been delivered to the subscription. As
specified in section 3.1.4.8, the subscription object contains the position
where the events start in the channels, once the new event is delivered to the
client, the server is able to update the position value it saves in the
subscription object so that it can perform the tracking task of the events
delivery. The server SHOULD track the new events generation from any of the
registered publishers in order for it to deliver the coming events to the
client in a timely manner. See <a href="https://go.microsoft.com/fwlink/?LinkId=208276" data-linktype="external">[MSDN-ProcessTrace]</a>
for a suggested implementation.</p><p>The server returns the result in the five output parameters:
<i>numActualRecords</i>, <i>eventDataIndices</i>, <i>eventDataSizes</i>, <i>resultBufferSize</i>,
and <i>resultBuffer</i>. On successful return, the <i>numActualRecords</i>
contains the number of events in the <i>resultBuffer</i>. All the returned
events are in BinXML format and they are packed as one binary blob in the <i>resultBuffer</i>.
The total size of all these events are marked by <i>resultBufferSize</i>. Since
all the events are packed together, there is a need to identify where the
separator is for each event in the result. To do this, the server fills two
arrays:  eventDataIndices and eventDataSizes. Both arrays contain the <i>numActualRecords</i>
of elements. For the eventDataIndices array, each array element is a 32-bit
value which is the start position of each event in the <i>resultBuffer</i>. For
the eventDataSizes array, each element is a 32-bit value which is the size of
every event.</p><p>The server SHOULD be notified by the underlying network that
the connection is lost from the client if the client abnormally terminates the
connection. The server abandons its operation for the client in such a case.
The server releases the subscription object it creates and free all associated
resources. The associated resources are described in
EvtRpcRegisterRemoteSubscription (Opnum 0) (section 3.1.4.8).</p><p>The server MUST return a value that indicates success or
failure for this operation.</p></div>