MQMgmtGetInfo

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

(Introduced in MSMQ 3.0.) The MQMgmtGetInfo function retrieves information about a queue or the Message Queuing installation on a computer.

HRESULT MQMgmtGetInfo(  
  LPCWSTR pMachineName,    
  LPCWSTR pObjectName,    
  MQMGMTPROPS * pMgmtProps         
);

Parameters

pMachineName

[in] A pointer to a Unicode string that contains the name of a computer. The computer can be specified using its UNC, DNS, or IP address. The local computer can be specified by setting this parameter to NULL.

pObjectName

[in] A pointer to a Unicode string that describes the type of object:

L"MACHINE" (MO_MACHINE_TOKEN)

Required when retrieving information about the queue manager.

L"QUEUE=<formatname>"

Required when retrieving information about a queue.

pMgmtProps

[in, out] A pointer to an MQMGMTPROPS structure that specifies the properties to be retrieved.

On input, the cProps member of the structure specifies the number of properties specified, the aPropID array specifies the identifiers of the properties, and the elements of the aPropVar array must be set to VT_NULL.

On output, the elements of the aPropVar array contain the returned property values.

On output, no return codes are set in the aStatus array.

Return Values

MQ_OK

Indicates success.

MQ_ERROR (0xC00E0001)

A non-specific Message Queuing error was generated. For example, information about a queue that is currently not the active queue was requested.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

The access rights for retrieving information about the applicable msmq (MSMQ-Configuration) or queue object are not allowed for the calling process.

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

The specified format name in pObjectName is illegal.

MQ_ERROR_ILLEGAL_PROPERTY_VT (0xC00E0019)

An invalid type indicator was supplied for one of the properties specified in pMgmtProps.

MQ_ERROR_QUEUE_NOT_ACTIVE (0xC00E0004)

The queue is not open or may not exist.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_INFORMATION_UNSUPPORTED_PROPERTY (0x400E0004)

An unsupported property identifier was specified in pMgmtProps.

Remarks

This function is used to retrieve two distinct sets of properties. Use the following guidelines when making calls to this function:

If the pObjectName parameter specifies a computer, retrieve only those properties that start with PROPID_MGMT_MSMQ.
If the pObjectName parameter specifies a queue, retrieve only those properties that start with PROPID_MGMT_QUEUE.

Note

These properties can be retrieved only for active queues.

The type indicator of each property specified must be set to VT_NULL. In this case, Message Queuing allocates the resources needed for the returned values. If it is not set to VT_NULL, the operation fails and an MQ_ERROR_ILLEGAL_PROPERTY_VT error is returned.

However, the application must call MQFreeMemory to free these resources after the returned values are not needed.

To retrieve information about a computer or a queue, the access rights for retrieving information about the applicable msmq (MSMQ-Configuration) or queue object must be allowed for the account under which the calling process is running. However, this requirement is ignored if the following registry entry is added.

HKLM\SOFTWARE\Microsoft\MSMQ\Parameters\RestrictAdminApi

If this entry is set to 1, only users that belong to the Local Administrators group are allowed to retrieve information about a computer or a queue using the MQMgmtGetInfo function.

Note

The functionality of the local administration API functions introduced in MSMQ 3.0 (MQMgmtAction, MQMgmtGetInfo, and MQPurgeQueue) is also available for computers running previous versions of Message Queuing. For more information, see MSMQ Local Admin API.

Equivalent COM Method

The COM equivalents of MQMgmtGetInfo are MSMQApplication for machine objects and MSMQManagement for queue objects.

Example Code

The following code example is included in Using Message Queuing.

For an example of	See
Retrieving a list of path names of all the private queues on a specified computer	C/C++ Code Example: Obtaining a List of Private Queues

Enumerating Subqueues

Subqueues under a given main queue can be enumerated by calling the MQMgmtGetInfo function. The management property PROPID_MGMT_QUEUE_SUBQUEUE_COUNT can be used to count the number of subqueues inside a given main queue. The management property PROPID_MGMT_QUEUE_SUBQUEUE_NAMES can be used to enumerate the list of names of all subqueues in a given main queue. The following sample code shows how to enumerate the subqueues in a main queue.

ULONG GetSubqueueInfo(const wstring& machineName, const wstring&,  
                                                       formatName)   
{  
    // Define the required constants and variables.  
    const int NUMBEROFPROPERTIES = 2;  // Number of properties  
    DWORD cPropId = 0;  // Property counter  
    // Define an MQMGMTROPS structure.  
    MQMGMTPROPS mgmtprops;  
    MGMTPROPID aMgmtPropId[NUMBEROFPROPERTIES];  
    MQPROPVARIANT aMgmtPropVar[NUMBEROFPROPERTIES];  
    // Retrieve the count of the subqueues.  
    aMgmtPropId[cPropId] = PROPID_MGMT_QUEUE_SUBQUEUE_COUNT;    
    aMgmtPropVar[cPropId].vt = VT_NULL;                  
    cPropId++;  
    // Retrieve the names of the subqueues.  
    aMgmtPropId[cPropId] = PROPID_MGMT_QUEUE_SUBQUEUE_NAMES;    
    aMgmtPropVar[cPropId].vt = VT_NULL;                  
    cPropId++;  
    // Initialize the MQMGMTPROPS structure.  
    mgmtprops.cProp = cPropId;   // number of management properties  
    mgmtprops.aPropID = aMgmtPropId;// management property IDs  
    mgmtprops.aPropVar = aMgmtPropVar;// management property values  
    mgmtprops.aStatus  = NULL;// no storage for error codes  
  
    wstring objectName = L"QUEUE=" + formatName;  
    HRESULT hr = MQMgmtGetInfo(machineName.c_str(),   
            objectName.c_str(), &mgmtprops);  
    ULONG subqueueCount = aMgmtPropVar[0].lVal;  
    wcout << L"Subqueue count is " << subqueueCount << endl;  
  
    ULONG nameCount = aMgmtPropVar[1].calpwstr.cElems;  
        wcout << L"Subqueue name count is " << nameCount << endl;  
    wcout << L"Subqueue list: ";  
    for(int i=0; i < nameCount; i++)  
    {  
        wcout << aMgmtPropVar[1].calpwstr.pElems[i] << L" ";  
    }  
    wcout << endl;  
    // Free the memory allocated to store the subqueue names.  
    for (int i = 0; i < aMgmtPropVar[1].calpwstr.cElems; i++)  
    {  
        MQFreeMemory(aMgmtPropVar[1].calpwstr.pElems[i]);  
    }  
    MQFreeMemory(aMgmtPropVar[1].calpwstr.pElems);  
    return subqueueCount;  
}

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows Server 2003.

Windows 95/98/Me: Unsupported.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.