3.1.4.2 R_QMMgmtAction (Opnum 1)
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.