C++ Code Example: Locating a Queue

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

This example describes a function that can be called to locate all public queues in the directory service that have a specific service type GUID. The Message Queuing functions used in this example include the following.

• MQLocateBegin: Starts a query by specifying the search criteria and the queue properties to be retrieved and returns a query handle. Note that any queue property other than the queue path name can be specified as a search criterion.

• MQLocateNext: Returns the next set of queue properties (the set of queue properties for the next queue) in the query results.

• MQLocateEnd: Releases the resources used in the query.

Locating Queues Based on Service Type GUID

The following procedure shows how to locate queues based on their service type GUID (the PROPID_Q_TYPE property).

To run a query based on the service type GUID of the queues

1. Specify the search criteria for the query using MQPROPERTYRESTRICTION and MQRESTRICTION.

2. Specify the properties to retrieve for the queues located using MQCOLUMNSET.

3. Call MQLocateBegin to start the query.

4. In a loop, call MQLocateNext to look at the query results.

5. Call MQLocateEnd to release the resources used in the query.

Code Example

The following example is a stand-alone module that calls an application-defined function that locates queues based on their service type GUID (the PROPID_Q_TYPE property). This module can be used as a template for calling other functions that can open the queue, send messages, or retrieve messages. Comment blocks indicate where these other functions can be called.

// Define the MQPROPERTYRESTRICTION   
// and MQRESTRICTION structures.  
const int MAX_PROPERTIES = 13;   // 13 possible queue properties  
CLSID PRINTER_SERVICE_TYPE =     // Dummy GUID  
      {0x1, 0x2, 0x3, {0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xa, 0xb}};  
HRESULT hr = MQ_OK;  
MQPROPERTYRESTRICTION PropertyRestriction;  
MQRESTRICTION Restriction;  
  
//////////////////////////////////////////  
// Set search criteria according to the   
// type of service provided by the queue.  
/////////////////////////////////////////  
  
// Set the queue restriction to PROPID_Q_TYPE = PRINTER_SERVICE_TYPE.  
PropertyRestriction.rel = PREQ;  
PropertyRestriction.prop = PROPID_Q_TYPE;  
PropertyRestriction.prval.vt = VT_CLSID;  
PropertyRestriction.prval.puuid = &PRINTER_SERVICE_TYPE;  
  
// Specify one property restriction.  
Restriction.cRes = 1;  
Restriction.paPropRes = &PropertyRestriction;  
  
// Set a MQCOLUMNSET structure to specify  
// the properties to be returned:           
// PROPID_Q_INSTANCE and PROPID_Q_CREATE_TIME.  
MQCOLUMNSET Column;  
PROPID aPropId[2];     // Only two properties to retrieve  
DWORD dwColumnCount = 0;  
  
aPropId[dwColumnCount] = PROPID_Q_INSTANCE;  
dwColumnCount++;  
  
aPropId[dwColumnCount] = PROPID_Q_CREATE_TIME;  
dwColumnCount++;  
  
Column.cCol = dwColumnCount;  
Column.aCol = aPropId;  
  
// Call MQLocateBegin to start a query.  
HANDLE         hEnum = NULL;  
hr = MQLocateBegin(  
                   NULL,           //Start search at the top  
                   &Restriction,   //Search criteria  
                   &Column,        //Properties to return  
                   NULL,           //No sort order  
                   &hEnum          //Enumeration handle  
                   );  
  
if (FAILED(hr))  
{  
  //  
  // Error handling.  
  //  
}  
  
// Call MQLocateNext in a loop to examine the  
// query results.  
MQPROPVARIANT aPropVar[MAX_PROPERTIES];  
DWORD cProps, index;  
  
do  
{  
  cProps = MAX_PROPERTIES;  
  hr = MQLocateNext(   
                    hEnum,         // Handle returned by MQLocateBegin  
                    &cProps,       // Size of aPropVar array  
                    aPropVar       // An array of MQPROPVARIANT for results  
                    );  
  
  if (FAILED(hr))  
  {  
    break;  
  }  
  
  for (index = 0; index < cProps; index += dwColumnCount)  
  
  {  
     // Process properties of a queue stored in:  
     // aPropVar[index], aPropVar[index + 1], …,  
     // aPropVar[index + dwColumnCount - 1].  
  }  
  
} while (cProps > 0);  
  
// Call MQLocateEnd to end query.  
hr = MQLocateEnd(hEnum);   // Handle returned by MQLocateBegin.  
if (FAILED(hr))  
{  
  //  
  //Error handling  
  //  
}