Share via

3.1.4.11 R_OpenQueueForMove (Opnum 11)

  • Article

The R_OpenQueueForMove method opens the queue and returns a QUEUE_CONTEXT_HANDLE_SERIALIZE (section 2.2.4.2) handle that can subsequently be used as the ullContextTo (destination queue) parameter of a call to the R_MoveMessage (Opnum 10) (section 3.1.4.10) method. This method MUST be called before the R_MoveMessage method.<21>

 void R_OpenQueueForMove(
   [in] handle_t hBind,
   [in] QUEUE_FORMAT* pQueueFormat,
   [in] DWORD dwAccess,
   [in] DWORD dwShareMode,
   [in] GUID* pClientId,
   [in] LONG fNonRoutingServer,
   [in] unsigned char Major,
   [in] unsigned char Minor,
   [in] USHORT BuildNumber,
   [in] LONG fWorkgroup,
   [out] ULONGLONG* pMoveContext,
   [out] QUEUE_CONTEXT_HANDLE_SERIALIZE* pphContext
 );

hBind: MUST specify an RPC binding handle parameter, as specified in [MS-RPCE] section 2.

pQueueFormat: MUST be a pointer to a QUEUE_FORMAT ([MS-MQMQ] section 2.2.7) structure that identifies the queue to open. This value MUST NOT be NULL. The value of the m_qft member MUST be one of QUEUE_FORMAT_TYPE_PUBLIC, QUEUE_FORMAT_TYPE_PRIVATE, QUEUE_FORMAT_TYPE_DIRECT, QUEUE_FORMAT_TYPE_MACHINE, or QUEUE_FORMAT_TYPE_SUBQUEUE.

dwAccess: Specifies the required type of access to the queue. MUST be set by the client to MQ_MOVE_ACCESS (0x00000004).

dwShareMode: Specifies whether the client needs exclusive access to the queue. MUST be set by the client to MQ_DENY_NONE (0x00000000), which permits multiple QUEUE_CONTEXT_HANDLE_SERIALIZE handles to the queue to be opened concurrently.

pClientId: MUST be set by the client to a pointer to a valid GUID that uniquely identifies the client. When the queue manager acts as the client, the queue manager sets this value to the Identifier ADM attribute of the local QueueManager ADM element instance. The server SHOULD ignore this parameter. This value MUST NOT be NULL.

fNonRoutingServer: If the client is configured to operate in the role of an MSMQ routing server, this parameter MUST be set to FALSE (0x00000000); otherwise, it MUST be set to TRUE (0x00000001).<22> If the value of the fNonRoutingServer parameter is FALSE (0x00000000), the server MUST ignore the pClientId parameter.

Name

Value

FALSE

0x00000000

TRUE

0x00000001

Major: MUST be set by the client to an implementation-specific Major Version number of the client. SHOULD<23> be ignored by the server.

Minor: MUST be set by the client to an implementation-specific Minor Version number of the client. SHOULD<24> be ignored by the server.

BuildNumber: MUST be set by the client to an implementation-specific Build Number of the client. SHOULD<25> be ignored by the server.

fWorkgroup: MUST be set to TRUE (0x00000001) by the client if the client machine is not a member of a Windows domain; otherwise, it MUST be set to FALSE (0x00000000). The RPC authentication level required by the server MAY be based on this value in subsequent calls on the interface.<26>

Name

Value

FALSE

0x00000000

TRUE

0x00000001

pMoveContext: The server MUST set this to a random value that can be used as the dwContextTo parameter in a subsequent call to the R_MoveMessage method. Logically, it represents a reference to the QUEUE_CONTEXT_HANDLE_SERIALIZE handle returned in the pphContext parameter.

pphContext: MUST be set by the server to a QUEUE_CONTEXT_HANDLE_SERIALIZE handle. A QUEUE_CONTEXT_HANDLE_SERIALIZE handle opened through a call to this method can be closed through a subsequent call to the R_CloseQueue (Opnum 3) (section 3.1.4.3) method.

Return Values: The method has no return values. If the method fails, an RPC exception is thrown.

Exceptions Thrown:

In addition to the exceptions thrown by the underlying RPC protocol [MS-RPCE], the method throws HRESULT failure codes as RPC exceptions. The client MUST treat all thrown HRESULT codes identically.

The client MUST disregard all out-parameter values when any failure HRESULT is thrown.

When processing this call, the server MUST do the following:

  • Look up the queue name in the QueueCollection ADM attribute of the local QueueManager ADM element instance. If not found, throw MQ_ERROR_QUEUE_NOT_FOUND (0xC00E0003).

  • Generate an Open Queue ([MS-MQDMPR] section 3.1.7.1.5) event with the following inputs:

    • iFormatName := pQueueFormat

    • iRequiredAccess := QueueAccessType.MoveAccess

    • iSharedMode := If dwShareMode is MQ_DENY_NONE then QueueShareMode.DenyNone else QueueShareMode.DenyReceive.

  • If rStatus is MQ_OK (0x00000000) then

    • Set the pphContext parameter to rOpenQueueDescriptor.Handle.

    • Set the pMoveContext parameter to a random value that logically references the handle value returned in the pphContext parameter.