Retrieving PROPID_Q_LABEL

The queue's label provides a description of the queue.

When you are retrieving PROPID_Q_LABEL, the type indicator in the MQQUEUEPROPS structure must be set to VT_NULL, and MQFreeMemory must be called after the return value is used. The VT_NULL setting tells MSMQ to allocate the memory needed for the returned label, and MQFreeMemory frees the MSMQ-allocated memory.

To retrieve PROPID_Q_LABEL

1. Define the structures needed to retrieve the properties. This includes the MQQUEUEPROPS structure.

   // Define number of properties to be retrieved.
   #define NumberOfProperties 1
   
   // Define property counter.
   DWORD PropIdCount = 0;
   
   // Define the MQQUEUPROPS structure.
   MQQUEUEPROPS QueueProps;
   PROPVARIANT aQueuePropVar[NumberOfProperties];
   QUEUEPROPID aQueuePropId[NumberOfProperties];
   HRESULT aQueueStatus[NumberOfProperties];
   
   // Define results.
   HRESULT hr;
   
   // Define format name buffer.
   DWORD dwFormatNameBufferLength = 256;
   WCHAR szFormatNameBuffer[256];
   

2. Specify PROPID_Q_LABEL. The type indicator must be set to VT_NULL so that MSMQ allocates memory for the label.

   aQueuePropId[PropIdCount] = PROPID_Q_LABEL;   //Property ID
   aQueuePropVar[PropIdCount].vt = VT_NULL;      //Type indicator
   PropIdCount++;
   

3. Add any additional queue properties. When adding properties, increment the NumberOfProperties variable to reflect the number of properties added.
4. Set the MQQUEUEPROPS structure.

   QueueProps.cProp = PropIdCount;           // Number of properties
   QueueProps.aPropID = aQueuePropId;        // Ids of properties
   QueueProps.aPropVar = aQueuePropVar;      // Values of properties
   QueueProps.aStatus = aQueueStatus;        // Error reports
   

5. Obtain the format name of the queue. The example below uses MQPathNameToFormatName to obtain the format name of a known queue. Other functions that can be used are MQHandleToFormatName and MQInstanceToFormatName.

   hr = MQPathNameToFormatName(L"machinename\\queuename",
                                 szFormatNameBuffer,
                                     &dwFormatNameBufferLength);
   if (FAILED(hr))
      {
      fprintf(stderr, "Failed in MQPathNameToFormatName, error = 0x%x\n",hr);
      return -1;
      }

6. Call MQGetQueueProperties.

   hr = MQGetQueueProperties(szFormatNameBuffer, &QueueProps);
   if (FAILED(hr))
      {
      fprintf(stderr, "Failed in MQGetQueueProperties, error = 0x%x\n",hr);
      return -1;
      }
    

7. Examine the value of the returned property. In this example, the authentication level of the queue is printed to the screen.

   wprintf(L"The label of the queue is :");
   wprintf(L" %s.\n", aQueuePropVar[0].pwszVal);
   

8. Call MQFreeMemory to free the memory allocated by MSMQ.

   MQFreeMemory(aQueuePropVar[0].pwszVal);
   if (FAILED(hr))
     {
     fprintf(stderr, "Failed in MQFreeMemory, error = 0x%x\n",hr);
     return -1;
     }
   

Example Code

The following example retrieves the PROPID_Q_LABEL property for a known queue and then prints the returned value to the screen. Note that the memory (used to store the label) allocated by MSMQ is freed using MQFreeMemory.

#include <windows.h>
#include <stdio.h>
#include <mq.h>                   // MSMQ header file



int main(int arg, char *argv[])

{
  ////////////////////////////
  //  Define structures.
  ////////////////////////////
  
  // Define the number of properties.
  #define NumberOfProperties 1
  
  // Define the property counter.
  DWORD PropIdCount = 0;
  
  //Define the MQQUEUPROPS structure.
  MQQUEUEPROPS QueueProps;
  PROPVARIANT aQueuePropVar[NumberOfProperties];
  QUEUEPROPID aQueuePropId[NumberOfProperties];
  HRESULT aQueueStatus[NumberOfProperties];
   
  //Define results.
  HRESULT hr;
  
  // Define format name buffer.
  DWORD dwFormatNameBufferLength = 256;
  WCHAR szFormatNameBuffer[256];
  
  
  ///////////////////////////////////
  // Specify PROPID_Q_LABEL. The type 
  // indicator must be set to VT_NULL.
  ///////////////////////////////////
  
  aQueuePropId[PropIdCount] = PROPID_Q_LABEL;    // Property ID
  aQueuePropVar[PropIdCount].vt = VT_NULL;       // Type indicator
  PropIdCount++;
  
  
  ///////////////////////////////////////////////////////
  // Add additional queue properties here. When adding 
  // properties, increment NumberOfProperties to 
  // reflect total number of properties.
  ///////////////////////////////////////////////////////
  
  
  ////////////////////////////////
  // Set the MQQUEUEPROPS structure.
  /////////////////////////////////
  QueueProps.cProp = PropIdCount;           // Number of properties
  QueueProps.aPropID = aQueuePropId;        // Ids of properties
  QueueProps.aPropVar = aQueuePropVar;      // Values of properties
  QueueProps.aStatus = aQueueStatus;        // Error reports
  
  
  ////////////////////////////
  //Get format name of queue.
  ////////////////////////////
  
  hr = MQPathNameToFormatName(L"machinename\\queuename",
                              szFormatNameBuffer,
                              &dwFormatNameBufferLength);
  if (FAILED(hr))
  {
    fprintf(stderr, "Failed in MQPathNameToFormatName, error = 0x%x\n",hr);
        return -1;
  }
  
  
  ////////////////////////////
  // Get queue property.
  ////////////////////////////
  
  hr = MQGetQueueProperties(szFormatNameBuffer, &QueueProps);
  if (FAILED(hr))
  {
    fprintf(stderr, "Failed in MQGetQueueProperties, error = 0x%x\n",hr);
        return -1;
  }
  
  
  ///////////////////////////////////////////////
  // Review returned value. This example prints 
  // out the label of the queue.
  //////////////////////////////////////////////
  
  wprintf(L"The label of the queue is :");
  wprintf(L" %s.\n", aQueuePropVar[0].pwszVal);
  
  
  /////////////////////////////////
  // Free memory allocated by MSMQ. 
  /////////////////////////////////
  
MQFreeMemory(aQueuePropVar[0].pwszVal);
   if (FAILED(hr))
    {
    fprintf(stderr, "Failed in MQFreeMemory, error = 0x%x\n",hr);
        return -1;
    }
  
  return 0;
  
}