<div class="content"><p> </p><p>The RemoteQMStartReceive2 method functions in the same way
as <span><a href="aab4d8fa-3a56-483c-ac61-4172a09fc199" data-linktype="relative-path">RemoteQMStartReceive (section 3.1.4.1)</a></span>,
except that it returns a structure that contains the <b>SequentialId</b> of the
<span><a href="33b1ac82-69ab-413c-9415-cd6f45d77156#gt_85c78cf0-1fb6-4e5d-85f5-a2e9f58a6b9e" data-linktype="relative-path">message</a></span>.<a id="Appendix_A_Target_25"></a><a aria-label="Product behavior note 25" href="d6c5ba0a-aaf8-489d-baf2-fdc286b4bea4#Appendix_A_25" data-linktype="relative-path">&lt;25&gt;</a></p><dl>
<dd>
<div><pre> HRESULT RemoteQMStartReceive2(
   [in] handle_t hBind,
   [out] PCTX_REMOTEREAD_HANDLE_TYPE* pphContext,
   [in, out] REMOTEREADDESC2* lpRemoteReadDesc2
 );
</pre></div>
</dd></dl><p><b>hBind: </b>MUST be set to an <span><a href="33b1ac82-69ab-413c-9415-cd6f45d77156#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a></span>
binding handle, as specified in <span><a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a></span>
section <span><a href="../ms-rpce/a01f5886-c485-4bcf-bb23-e0d755510ab7" data-linktype="relative-path">2</a></span>.</p><p><b>pphContext: </b>The server MUST return a non-NULL
value for this handle upon success for receive calls. This handle will be used
by the client in subsequent calls to <span><a href="4c0b91ba-37fa-441c-974a-91bbea58a62d" data-linktype="relative-path">RemoteQMEndReceive (section 3.1.4.2)</a></span>.
This handle MUST NOT be set upon failure or for peek calls. If this method
returns an error, <i>pphContext</i> is undefined and MUST NOT be used as an
argument for a call to RemoteQMEndReceive.</p><p><b>lpRemoteReadDesc2: </b>A pointer to an instance of
a <span><a href="d7cf6789-f160-4de2-8ed3-1ff812da1b4f" data-linktype="relative-path">REMOTEREADDESC2 (section 2.2.2.2)</a></span>
structure. The <b>SequentialId</b> member MUST be set to the least significant
7 bytes of the <b>Message.LookupIdentifier</b> (<span><a href="../ms-mqdmpr/5eafe0a6-a22f-436b-a0d9-4cbc25c52b47" data-linktype="relative-path">[MS-MQDMPR]</a></span>
section <span><a href="../ms-mqdmpr/9170afda-9524-4abd-91fe-8c53e51e0def" data-linktype="relative-path">3.1.1.12</a></span>)
of the message that is returned by this method.</p><dl>
<dd>
<p>The client MUST provide all parameters of <i>lpRemoteReadDesc2.pRemoteReadDesc</i>
that are marked as to be set by the client in section <span><a href="645e7b85-18f0-4f50-a905-1dd55565728b" data-linktype="relative-path">2.2.2.1</a></span>.</p>
</dd>
<dd>
<p>The <i>lpRemoteReadDesc2.pRemoteReadDesc.ulAction</i>
parameter MUST be one of the following values.</p>
</dd></dl><table><thead>
  <tr>
   <th>
   <p>Value of ulAction</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>
  <p>MQ_ACTION_RECEIVE</p>
  <p>0x00000000</p>
  </td>
  <td>
  <p>If <i>hCursor</i> is nonzero, read and remove the
  first message available at the current cursor location walking toward the end
  of the queue.</p>
  <p>If <i>hCursor</i> is zero, read and remove the message
  from the front of the queue.</p>
  </td>
 </tr><tr>
  <td>
  <p>MQ_ACTION_PEEK_CURRENT</p>
  <p>0x80000000</p>
  </td>
  <td>
  <p>If <i>hCursor</i> is nonzero, read the message at the
  current cursor location, but do not remove it from the queue. The cursor
  location does not change after the operation.</p>
  <p>If <i>hCursor</i> is zero, read the message at the
  front of the queue, but do not remove it from the queue.</p>
  </td>
 </tr><tr>
  <td>
  <p>MQ_ACTION_PEEK_NEXT</p>
  <p>0x80000001</p>
  </td>
  <td>
  <p>Read the message following the message at the current
  cursor location, but do not remove it. The cursor location will then change
  to the next available message, walking toward the end of the queue.</p>
  <p>The <i>hCursor</i> parameter MUST be set to a nonzero
  cursor handle.</p>
  </td>
 </tr></tbody></table><dl>
<dd>
<p>The <i>hCursor</i> member of <i>lpRemoteReadDesc</i>
specifies a handle to an opened cursor. A value of zero indicates that a cursor
is not used for this operation.</p>
</dd></dl><p>The <b>dwRequestID</b> member of the <i>lpRemoteReadDesc</i>
parameter is used in a subsequent call to RemoteQMEndReceive or <span><a href="76f56b96-7c8d-432e-a169-a1b750e20527" data-linktype="relative-path">RemoteQMCancelReceive</a></span>
to correlate that call with the call to RemoteQMStartReceive2.</p><p><b>Return Values: </b>On success, this method MUST return
MQ_OK (0x00000000).</p><p>If an error occurs, the server MUST return a failure <span><a href="../ms-dtyp/a9046ed2-bfb2-4d56-a719-2824afce59ac" data-linktype="relative-path">HRESULT</a></span>,
and the client MUST treat all failure HRESULTs identically. </p><p><b>Exceptions Thrown:</b> No exceptions are thrown except
those thrown by the underlying RPC protocol, as specified in [MS-RPCE].</p><p>While processing this method, the server MUST:</p><ul><li><p><span><span> 
</span></span>Return MQ_ERROR_INVALID_HANDLE (0xC00E0007) if <i>lpRemoteReadDesc2</i>
is NULL.</p>
</li><li><p><span><span> 
</span></span>Return MQ_ERROR_INVALID_HANDLE (0xC00E0007) if <i>lpRemoteReadDesc2.pRemoteReadDesc</i>
is NULL.</p>
</li><li><p><span><span> 
</span></span>Return MQ_ERROR_INVALID_PARAMETER (0xC00E0006) if <i>lpRemoteReadDesc2.pRemoteReadDesc.dwQueue</i>
is set to 0x00000000 or <i>lpRemoteReadDesc2.pRemoteReadDesc.dwQueue</i> is not
equal to <i>lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue</i>.</p>
</li><li><p><span><span> 
</span></span>The server SHOULD return MQ_ERROR_INVALID_PARAMETER (0xC00E0006)
if the <i>lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID</i> does not uniquely
identify the receive request. This duplicate detection is performed by
searching for a <b>RemoteReadEntry</b>, referred to as <b>rRemoteReadEntry</b>,
in <b>rRemoteReadEntryCollection</b> such that <b>rRemoteReadEntry.OpenQueueDescriptorHandle</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue</i> and <b>rRemoteReadEntry.RequestId</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID</i>.<a id="Appendix_A_Target_26"></a><a aria-label="Product behavior note 26" href="d6c5ba0a-aaf8-489d-baf2-fdc286b4bea4#Appendix_A_26" data-linktype="relative-path">&lt;26&gt;</a></p>
</li><li><p><span><span> 
</span></span>Return <i>STATUS_INVALID_PARAMETER (0xC000000D)</i> if <i>lpRemoteReadDesc2.pRemoteReadDesc.hCursor</i>
is set to 0x00000000 and the <i>lpRemoteReadDesc2.pRemoteReadDesc.ulAction</i>
is set to MQ_ACTION_PEEK_NEXT.</p>
</li><li><p><span><span> 
</span></span>Search the <b>rOpenQueueEntryCollection</b> where <b>OpenQueueEntry.OpenQueueDescriptorHandle</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue</i>.</p>
</li><li><p><span><span> 
</span></span>If the <b>OpenQueueDescriptorHandle</b> is not found, return
MQ_ERROR_INVALID_PARAMETER (0xC00E0006).</p>
</li><li><p><span><span> 
</span></span>Find the <b>OpenQueueDescriptor</b>, referred to as <b>rOpenQueueDescriptor</b>,
in the <b>Queue.OpenQueueDescriptorCollection</b> of each queue object in <b>QueueManager.QueueCollection</b>
such that <b>rOpenQueueDescriptor.Handle</b> = <i>lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue</i>.</p>
</li><li><p><span><span> 
</span></span>If <i>lpRemoteReadDesc2.pRemoteReadDesc.hCursor</i> is not
0x00000000, find the cursor object, referred to by <b>rCursor</b>, in the <b>rOpenQueueDescriptor.CursorCollection</b>
with a Handle property equal to <i>lpRemoteReadDesc2.pRemoteReadDesc.hCursor</i>.</p>
</li><li><p><span><span> 
</span></span>If no cursor object is found, return STATUS_INVALID_PARAMETER.</p>
</li><li><p><span><span> 
</span></span>If <i>lpRemoteReadDesc2.pRemoteReadDesc.hCursor</i> is
0x00000000, set <b>rCursor</b> to NULL.</p>
</li><li><p><span><span> 
</span></span>Create a new <b>RemoteReadEntry</b>, referred to as <i>rrEntry</i>,
with the following attributes:</p>
<ul><li><p><span><span>  </span></span><b>OpenQueueDescriptorHandle</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue</i></p>
</li><li><p><span><span>  </span></span><b>Timeout</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout</i></p>
</li><li><p><span><span>  </span></span><b>UserMessagePacket</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.lpBuffer</i></p>
</li><li><p><span><span>  </span></span><b>Action</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.ulAction</i></p>
</li><li><p><span><span>  </span></span><b>RequestId</b>
= <i>lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID</i></p>
</li></ul></li><li><p><span><span> 
</span></span>Add <i>rrEntry</i> to <b>rRemoteReadEntryCollection</b>.</p>
</li><li><p><span><span> 
</span></span>If the <b>ulAction</b> member of the <i>lpRemoteReadDesc2.pRemoteReadDesc</i>
parameter is MQ_ACTION_RECEIVE, generate a <span><a href="../ms-mqdmpr/e322d06b-5bd6-4cb0-abbb-4485526834a6" data-linktype="relative-path">Dequeue
Message Begin</a></span> event ([MS-MQDMPR] section 3.1.7.1.11) with the following
inputs:</p>
<ul><li><p><span><span>  </span></span><i>iQueueDesc</i>
:= <b>rOpenQueueDescriptor</b> obtained in a preceding step.</p>
</li><li><p><span><span>  </span></span><i>iTimeout</i>
:= <i>lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout</i>.</p>
</li><li><p><span><span>  </span></span><i>iTag</i>
:= <i>lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID</i>.</p>
</li><li><p><span><span>  </span></span><i>iCursor</i>
:= <i>rCursor</i>.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the <b>ulAction</b> member of the <i>lpRemoteReadDesc2.pRemoteReadDesc</i>
parameter is MQ_ACTION_PEEK_CURRENT, generate a <span><a href="../ms-mqdmpr/658f62aa-ac0f-4916-b6dc-d4fa7539b62d" data-linktype="relative-path">Peek
Message</a></span> ([MS-MQDMPR] section 3.1.7.1.15) event with the following
inputs:</p>
<ul><li><p><span><span>  </span></span><i>iQueueDesc</i>
:= <b>rOpenQueueDescriptor</b> obtained in a preceding step.</p>
</li><li><p><span><span>  </span></span><i>iTimeout</i>
:= <i>lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout</i>.</p>
</li><li><p><span><span>  </span></span><i>iCursor</i>
:= <i>rCursor</i>.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the <b>ulAction</b> member of the <i>lpRemoteReadDesc2.pRemoteReadDesc</i>
parameter is MQ_ACTION_PEEK_NEXT, generate a <span><a href="../ms-mqdmpr/032bebe9-fbdc-4cb4-a10a-f3fcad2314f5" data-linktype="relative-path">Peek Next
Message</a></span> ([MS-MQDMPR] section 3.1.7.1.14) event with the following
inputs:</p>
<ul><li><p><span><span>  </span></span><i>iQueueDesc</i>
:= <b>rOpenQueueDescriptor</b> obtained in a preceding step.</p>
</li><li><p><span><span>  </span></span><i>iTimeout</i>
:= <i>lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout</i>.</p>
</li><li><p><span><span>  </span></span><i>iCursor</i>
:= <i>rCursor</i>.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the <i>rStatus</i> value returned from the preceding events is
MQ_OK (0x00000000), the server MUST process the returned <i>rMessage</i> as
follows:</p>
<ul><li><p><span><span>  </span></span>Generate
a <span><a href="../ms-mqdmpr/e7e9aebc-e278-4a85-baa5-9caf1548dcee" data-linktype="relative-path">Construct
a UserMessage Packet</a></span> ([MS-MQDMPR] section 3.1.7.1.30) event with the
following argument:</p>
<ul><li><p><span><span> 
</span></span><i>iMessage</i> := <i>rMessage</i></p>
</li></ul></li><li><p><span><span>  </span></span>Generate
a <span><a href="../ms-mqdmpr/b0e19729-af80-4cca-841f-865d8fc4a028" data-linktype="relative-path">Serialize
Message to Buffer</a></span> ([MS-MQDMPR] section 3.1.7.1.32) event with the
following arguments:</p>
<ul><li><p><span><span> 
</span></span><i>iMessage</i> := <i>rMessage</i></p>
</li><li><p><span><span> 
</span></span><i>iBuffer</i> := <i>rUserMessage</i> returned by the  Construct
a UserMessage Packet event.</p>
</li></ul></li><li><p><span><span>  </span></span>Assign
<i>rUserMessage</i> to <i>lpRemoteReadDesc2</i>.<b>pRemoteReadDesc</b>.<b>lpBuffer</b>.</p>
</li><li><p><span><span>  </span></span>Assign
<i>rUserMessage</i>.<b>BaseHeader</b>.<b>PacketSize</b> to <i>lpRemoteReadDesc2</i>.<b>pRemoteReadDesc</b>.<b>dwSize</b></p>
</li><li><p><span><span>  </span></span>Assign
the least significant seven bytes of <i>rMessage.LookupIdentifier</i> to the <b>SequentialId</b>
member of <i>lpRemoteReadDesc2</i>.</p>
</li></ul></li><li><p><span><span> 
</span></span>Remove the <b>RemoteReadEntry</b> ADM element instance from <b>rRemoteReadEntryCollection</b>
for which <b>RemoteReadEntry</b>.<b>RequestId</b> equals <i>lpRemoteReadDesc2</i>.<b>pRemoteReadDesc</b>.<b>dwRequestID</b>
and <b>RemoteReadEntry</b>.<b>OpenQueueDescriptorHandle</b> equals <i>lpRemoteReadDesc2</i>.<b>pRemoteReadDesc</b>.<b>hRemoteQueue</b>.</p>
</li><li><p><span><span> 
</span></span>If <i>rStatus</i> is MQ_OK (0x00000000) and <i>lpRemoteReadDesc2.pRemoteReadDesc.ulAction</i>
is MQ_ACTION_RECEIVE, set <i>pphContext</i> to <i>rrEntry</i>; otherwise,
delete <i>rrEntry</i>.</p>
</li><li><p><span><span> 
</span></span>Return <i>rStatus</i>.</p>
</li></ul></div>