3.1.4.2 R_QMMgmtAction (Opnum 1)

  • Article

The R_QMMgmtAction method requests the server to perform a management function on a specific queue or MSMQ installation.

 HRESULT R_QMMgmtAction(
     [in] handle_t hBind,
     [in] const MGMT_OBJECT* pObjectFormat,
     [in] const wchar_t * lpwszAction
     );

hBind: An RPC binding handle, as specified in [MS-RPCE] section 2.

pObjectFormat: A pointer to a MGMT_OBJECT structure that specifies the queue or computer to which the action is being applied.

lpwszAction:  A pointer to a null-terminated Unicode string that specifies the action to perform on the computer. The lpwszAction value MUST be one of the following (the value is not case-sensitive).

Value

Meaning

"CONNECT"

 A machine action. Connects the computer to the network and the MSMQ Directory Service server.

"DISCONNECT"

A machine action. Disconnects the computer from the network and the MSMQ Directory Service server.

"TIDY"

A machine action. Cleans up empty message files. MSMQ does this every 6 hours. It is helpful when a large number of messages are deleted (purged or received by an application), and the application needs the disk space immediately.

"PAUSE"

A queue action. Valid for outgoing queues only. Stops the sending of messages from the computer. The queue manager will not send messages to the applicable destination queue until a RESUME action is initiated.

"RESUME"

A queue action. Valid for outgoing queues only. Restarts the sending of messages after a PAUSE action is initiated.

"EOD_RESEND"

A queue action. Resends the pending transaction sequence.

Return Values: On success, this method MUST return MQ_OK (0x00000000).

MQ_OK (0x00000000)

MQ_ERROR (0xC00E0001)

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

If pObjectFormat specifies an MgmtObjectType of MGMT_SESSION or an lpwszAction has different value than those in the table above, the call MUST fail and the error message MAY be MQ_ERROR_INVALID_PARAMETER (0xC00E0006).<17>

If an error occurs, the server MUST return a failure HRESULT.

The opnum field value for this method MUST be 1 and is received at a dynamically assigned endpoint supplied by the RPC endpoint mapper, as specified in [MS-RPCE].

For MSMQ error codes, see [MSDN-MQEIC]. The structure and sequence of data on the wire are specified in the Transfer Syntax NDR section in [C706].

While processing this call, the server MUST use the QueueManager and Queue data elements as specified in [MS-MQDMPR] sections 3.1.1.1 and 3.1.1.2.

 While processing this call, the server MUST generate the following events specified in [MS-MQDMPR]:

 The above-described data elements and events MUST be used as follows:

  • If lpwszAction EQUALS "CONNECT" then generate the Bring Online event.

  • If lpwszAction EQUALS "DISCONNECT" then generate the Take Offline event.

  • If lpwszAction EQUALS "TIDY" then for each Queue in QueueManager.QueueCollection, generate the Purge Queue event with following inputs:

    • IQueue : = reference to a Queue specified by element from QueueManager.QueueCollection.

  • If lpwszAction EQUALS "PAUSE" then generate a Pause Queue event with following inputs:

    • IQueue : = reference to a Queue specified by pQueueFormat from pObjectFormat.

  • If lpwszAction EQUALS "RESUME" then generate a Resume Queue event with following inputs:

    • IQueue : = reference to a Queue specified by pQueueFormat from pObjectFormat.

  • If lpwszAction EQUALS "EOD_RESEND" then generate a Resend Transactional Sequence event with following inputs:

    • IQueue : = reference to a Queue specified by pQueueFormat from pObjectFormat.