3.1.4.1 R_QMMgmtGetInfo (Opnum 0)
The R_QMMgmtGetInfo method requests information on an MSMQ installation on a server or on a specific queue.
-
HRESULT R_QMMgmtGetInfo( [in] handle_t hBind, [in] const MGMT_OBJECT* pObjectFormat, [in, range(1,128)] DWORD cp, [in, size_is(cp)] ULONG aProp[], [in, out, size_is(cp)] PROPVARIANT apVar[] );
hBind: An RPC binding handle, as specified in [MS-RPCE] section 2.
pObjectFormat: A pointer to an MGMT_OBJECT structure that defines the queue or computer on which to return information.
cp: The length (in elements) of the arrays aProp and apVar MUST be at least 1, and MUST be at most 128.
aProp: Points to an array of property identifiers associated with the array of property values. This array MUST contain at least one element. Each element MUST specify a value from the property identifiers table, as specified in section 2.2.3. Each element MUST specify the property identifier for the corresponding property value at the same element index in apVar. This array and the array to which apVar points MUST be of the same length.
apVar: Points to an array that specifies the property values associated with the array of property identifiers. Each element in this array specifies the property value for the corresponding property identifier at the same element index in the array to which aProp points. This array MUST contain at least one element. The property value in each element MUST correspond accordingly to the property identifier from aProp, as specified in section 2.2.3, and MUST be set to VT_NULL<14> (as specified in [MS-MQMQ] section 2.2.12) before each call to R_QMMgmtGetInfo. This array and the array to which aProp points MUST be of the same length.
Return Values: On success, this method MUST return MQ_OK (0x00000000).
Return value/code |
Description |
---|---|
0x00000000 MQ_OK |
|
0xC00E0001 MQ_ERROR |
Generic error code. This error code is also the first of several error codes beginning with the string "MQ_ERR". A list of the errors prefaced with "MQ-ERR" is specified in 2.4. |
Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].
If an error occurs, the server MUST return a failure HRESULT and MUST NOT set any [out] parameter values.
The opnum field value for this method MUST be 0 and is received at a dynamically assigned endpoint supplied by the RPC endpoint mapper, as specified in [MS-RPCE].
If the pObjectFormat parameter specifies an MgmtObjectType of MGMT_MACHINE, the server MUST return only those properties that pertain to the MSMQ installation. If pObjectFormat specifies an MgmtObjectType of MGMT_QUEUE, the server MUST return only those properties that pertain to a queue. If pObjectFormat specifies an MgmtObjectType of MGMT_SESSION, the call MUST fail, and the error message MAY be MQ_ERROR_INVALID_PARAMETER (0xC00E0006).<15>
If the pObjectFormat parameter specifies a computer, and one or more of the properties specified in aProp are different than those specified in section 2.2.3.1, the call MAY fail with MQ_ERROR_ILLEGAL_PROPID (0xC00E0039). If the pObjectFormat parameter specifies a queue, and one or more of the properties specified in aProp are different than those specified in section 2.2.3.2, the call MAY fail with MQ_ERROR_ILLEGAL_PROPID (0xC00E0039).<16>
MSMQ properties are specified in [MS-MQMQ] section 2.
For MSMQ error codes, see [MSDN-MQEIC]. The structure and sequence of data on the wire are specified in [C706] Transfer Syntax NDR.
While processing this call, the server MUST use the QueueManager, Queue, OutgoingQueue, and OutgoingTransferInfo data elements as specified in [MS-MQDMPR] section 3.1.1 to populate apVar with values for corresponding property from aProp.
If the pObjectFormat parameter specifies an MgmtObjectType of MGMT_MACHINE, the server MUST use attributes of the QueueManager and Queue data elements.
For each property identifier in the aProp array, populate the corresponding position in the apVar array as follows:
Property Identifier |
Value |
Variant Type |
---|---|---|
A vector of all the queue names from QueueManager.QueueCollection, where Queue.Active EQUALS True. |
VT_LPWSTR VT_VECTOR |
|
A vector of path names of all the private queues from QueueManager.QueueCollection, where the Queue.QueueType EQUALS Private. |
VT_LPWSTR VT_VECTOR |
|
The first directory server in the list, QueueManager.DirectoryServerList. If the queue manager is not integrated with an MSMQ Directory Service, then apVar will be set to VT_NULL. |
VT_LPWSTR |
|
If QueueManager.ConnectionActive EQUALS True then "CONNECTED" else "DISCONNECTED". |
VT_LPWSTR |
|
MAY be set to an empty string. |
VT_LPWSTR |
|
Sum of all Queue.TotalBytes from the QueueManager.QueueCollection. |
VT_I8 |
If the pObjectFormat parameter specifies an MgmtObjectType of MGMT_QUEUE, the server MUST use attributes of the Queue, OutgoingQueue , and OutgoingTransferInfo objects as follows:
While processing this call, the Open Queue event SHOULD be used to get an OpenQueueDescriptor as specified in [MS-MQDMPR] sections 3.1.1.16 and 3.1.7.1.5 as following:
Generate an Open Queue event with the following inputs:
iFormatName := reference to a Queue specified by pQueueFormat from pObjectFormat.
iRequiredAccess := QueueAccessType.ReceiveAccess as specified in [MS-MQDMPR] section 3.1.1.17.
iSharedMode := QueueShareMode.DenyNone as specified in [MS-MQDMPR] section 3.1.1.17.
If rStatus NOT-EQUALS MQ_OK then R_QMMgmtGetInfo SHOULD exit with an MQ_ERROR HRESULT value.
Otherwise for each property identifier in the aProp array, populate the corresponding position in the apVar array as follows:
Property Identifier
Value
Variant Type
rOpenQueueDescriptor.QueueReference.Pathname.
VT_LPWSTR
rOpenQueueDescriptor.QueueReference.QualifiedPathname.
VT_LPWSTR
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue AND rOpenQueueDescriptor.QueueReference.Multicast EQUALS True then
"MULTICAST"
else If rOpenQueueDescriptor.QueueReference.QueueType EQUALS Public then
"PUBLIC"
else If rOpenQueueDescriptor.QueueReference.QueueType EQUALS Private then
"PRIVATE"
else If rOpenQueueDescriptor.QueueReference.QueueType EQUALS System then
"MACHINE"
else If rOpenQueueDescriptor.QueueReference.QueueType EQUALS Connector then
"CONNECTOR".
VT_LPWSTR
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
"REMOTE"
else
"LOCAL".
VT_LPWSTR
If rOpenQueueDescriptor.QueueReference.Transactional EQUALS True then
"YES"
else
"NO"
VT_LPWSTR
If QueueManager.DirectoryOffline is True
If rOpenQueueDescriptor.QueueReference.QueueType is Private
"NO"
else
"Unknown"
else
If QueueManager.ForeignSystem is True
"YES"
else
"NO"
VT_LPWSTR
to the number of MessagePosition elements in the rOpenQueueDescriptor.QueueReference.MessagePositionList that are not in the Deleted state.
VT_UI4
rOpenQueueDescriptor.QueueReference.TotalBytes.
VT_UI4
If rOpenQueueDescriptor.QueueReference. JournalQueueReference EQUALS NULL
else
The number of elements in the rOpenQueueDescriptor.QueueReference. JournalQueueReference.MessagePositionList.
VT_UI4
If rOpenQueueDescriptor.QueueReference.Journaling EQUALS True then rOpenQueueDescriptor.QueueReference. JournalQueueReference.TotalBytes.. else0.
VT_UI4
If rOpenQueueDescriptor.QueueReference is not of type OutgoingQueue then
"LOCAL CONNECTION"
else If rOpenQueueDescriptor.QueueReference.State EQUALS Connected then
"CONNECTED"
else If rOpenQueueDescriptor.QueueReference.State EQUALS Disconnected then
"DISCONNECTED"
else If rOpenQueueDescriptor.QueueReference.State EQUALS Disconnecting then
"DISCONNECTING"
else If rOpenQueueDescriptor.QueueReference.State EQUALS Inactive then
"INACTIVE"
else If rOpenQueueDescriptor.QueueReference.State EQUALS Locked then
"LOCKED"
else If rOpenQueueDescriptor.QueueReference.State EQUALS NeedValidation then
"NEED VALIDATION"
else If rOpenQueueDescriptor.QueueReference.State EQUALS Waiting then
"WAITING"
else If rOpenQueueDescriptor.QueueReference.State EQUALS OnHold then
"ONHOLD".
VT_LPWSTR
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue
If rOpenQueueDescriptor.QueueReference.State
EQUALS Connected
If rOpenQueueDescriptor.QueueReference.Multicast
EQUALS True then
rOpenQueueDescriptor.QueueReference.QualifiedPathname
else
rOpenQueueDescriptor.QueueReference.NextHops
else If rOpenQueueDescriptor.QueueReference.State
EQUALS Waiting then
rOpenQueueDescriptor.QueueReference.NextHops.
VT_LPWSTR
VT_VECTOR
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue AND rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodNoAckCount > 0
then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodLastAck serialized into a byte array according to the SEQUENCE_INFO structure specified in [MS-MQMQ] section 2.2.5.1.
VT_BLOB
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodLastAckTime.
VT_I4
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodLastAckCount.
VT_UI4
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodFirstNonAck.
VT_BLOB
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodLastNonAck.
VT_BLOB
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodNextSeq.
VT_BLOB
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference.OutgoingTransferInfoReference.EodNoReadCount.
VT_UI4
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodNoAckCount.
VT_UI4
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodResendTime.
VT_I4
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodResendInterval.
VT_UI4
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodResendCount.
VT_UI4
rOpenQueueDescriptor.QueueReference.IncomingTransactionalTransferInfoCollection. The IncomingTransactionalTransferInfoCollection ADM element is to be formatted into a Variant VT_VECTOR type as specified in [MS-MQMQ] section 2.3.12.24.
VT_VARIANT
VT_VECTOR
If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then
the rOpenQueueDescriptor.QueueReference.OutgoingQueue.ConnectionHistory ADM element.attribute tuple is formatted into a VT_VECTOR, as specified in [MS-MQMQ] section 2.3.12.25.
VT_VARIANT
VT_VECTOR
The number of elements in the rOpenQueueDescriptor.QueueReference.SubqueueCollection.
VT_UI4
The vector of all subqueue names in the rOpenQueueDescriptor.QueueReference.SubqueueCollection.
VT_VARIANT
VT_VECTOR