3.1.4.1 R_QMMgmtGetInfo (Opnum 0)

  • Article

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

PROPID_MGMT_MSMQ_ACTIVEQUEUES

A vector of all the queue names from QueueManager.QueueCollection, where Queue.Active EQUALS True.

VT_LPWSTR

VT_VECTOR

PROPID_MGMT_MSMQ_PRIVATEQ

A vector of path names of all the private queues from QueueManager.QueueCollection, where the Queue.QueueType EQUALS Private.

VT_LPWSTR

VT_VECTOR

PROPID_MGMT_MSMQ_DSSERVER

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

PROPID_MGMT_MSMQ_CONNECTED

If QueueManager.ConnectionActive EQUALS True then

 "CONNECTED"

else

 "DISCONNECTED".

VT_LPWSTR

PROPID_MGMT_MSMQ_TYPE

MAY be set to an empty string.

VT_LPWSTR

PROPID_MGMT_MSMQ_BYTES_IN_ALL_QUEUES

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

    PROPID_MGMT_QUEUE_PATHNAME

    rOpenQueueDescriptor.QueueReference.Pathname.

    VT_LPWSTR

    PROPID_MGMT_QUEUE_FORMATNAME

    rOpenQueueDescriptor.QueueReference.QualifiedPathname.

    VT_LPWSTR

    PROPID_MGMT_QUEUE_TYPE

    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

    PROPID_MGMT_QUEUE_LOCATION

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    "REMOTE"

    else

     "LOCAL".

    VT_LPWSTR

    PROPID_MGMT_QUEUE_XACT

    If rOpenQueueDescriptor.QueueReference.Transactional EQUALS True then

     "YES"

    else

     "NO"

    VT_LPWSTR

    PROPID_MGMT_QUEUE_FOREIGN

    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

    PROPID_MGMT_QUEUE_MESSAGE_COUNT

     to the number of MessagePosition elements in the rOpenQueueDescriptor.QueueReference.MessagePositionList that are not in the Deleted state.

    VT_UI4

    PROPID_MGMT_QUEUE_BYTES_IN_QUEUE

    rOpenQueueDescriptor.QueueReference.TotalBytes.

    VT_UI4

    PROPID_MGMT_QUEUE_JOURNAL_MESSAGE_COUNT

    If rOpenQueueDescriptor.QueueReference. JournalQueueReference EQUALS NULL

    else

         The number of elements in the rOpenQueueDescriptor.QueueReference. JournalQueueReference.MessagePositionList.

    VT_UI4

    PROPID_MGMT_QUEUE_BYTES_IN_JOURNAL

    If rOpenQueueDescriptor.QueueReference.Journaling EQUALS True then    rOpenQueueDescriptor.QueueReference. JournalQueueReference.TotalBytes.. else0.

    VT_UI4

    PROPID_MGMT_QUEUE_STATE

    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

    PROPID_MGMT_QUEUE_NEXTHOPS

    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

    PROPID_MGMT_QUEUE_EOD_LAST_ACK

    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

    PROPID_MGMT_QUEUE_EOD_LAST_ACK_TIME

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodLastAckTime.

    VT_I4

    PROPID_MGMT_QUEUE_EOD_LAST_ACK_COUNT

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodLastAckCount.

    VT_UI4

    PROPID_MGMT_QUEUE_EOD_FIRST_NON_ACK

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodFirstNonAck.

    VT_BLOB

    PROPID_MGMT_QUEUE_EOD_LAST_NON_ACK

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodLastNonAck.

    VT_BLOB

    PROPID_MGMT_QUEUE_EOD_NEXT_SEQ

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodNextSeq.

    VT_BLOB

    PROPID_MGMT_QUEUE_EOD_NO_READ_COUNT

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference.OutgoingTransferInfoReference.EodNoReadCount.

    VT_UI4

    PROPID_MGMT_QUEUE_EOD_NO_ACK_COUNT

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodNoAckCount.

    VT_UI4

    PROPID_MGMT_QUEUE_EOD_RESEND_TIME

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodResendTime.

    VT_I4

    PROPID_MGMT_QUEUE_EOD_RESEND_INTERVAL

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodResendInterval.

    VT_UI4

    PROPID_MGMT_QUEUE_EOD_RESEND_COUNT

    If rOpenQueueDescriptor.QueueReference is of type OutgoingQueue then

    rOpenQueueDescriptor.QueueReference. OutgoingTransferInfoReference.EodResendCount.

    VT_UI4

    PROPID_MGMT_QUEUE_EOD_SOURCE_INFO

    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

    PROPID_MGMT_QUEUE_CONNECTION_HISTORY

    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

    PROPID_MGMT_QUEUE_SUBQUEUE_COUNT

    The number of elements in the rOpenQueueDescriptor.QueueReference.SubqueueCollection.

    VT_UI4

    PROPID_MGMT_QUEUE_SUBQUEUE_NAMES

    The vector of all subqueue names in the rOpenQueueDescriptor.QueueReference.SubqueueCollection.

    VT_VARIANT

    VT_VECTOR