The MQLocateBegin function starts a query to locate a single public queue (or set of public queues), returning a query handle. Use MQLocateNext to retrieve the query results.
This function does not return the number of matching entries.
HRESULT APIENTRY MQLocateBegin(
LPCWSTR lpwcsContext,
MQRESTRICTION *pRestriction,
MQCOLUMNSET *pColumns,
MQSORTSET *pSort,
PHANDLE phEnum
);
Queries can only locate public queues. MQLocateBegin cannot locate a private queue. For a complete description of running a query, see Locating a Public Queue.
The pRestriction parameter specifies the search criteria (which queue properties and values are used in the search). It is a pointer to a structure containing a list of property restrictions logically combined by the And operator, with each restriction including a queue property identifier, a property value, and a comparison operator. Comparison operators include: less than (PRLT), less than or equal to (PRLE), equal (PREQ), not equal (PRNE), greater than or equal to (PRGE), greater than (PRGT).
To specify the search criteria, MSMQ uses two structures: MQPROPERTYRESTRICTION and MQRESTRICTION. MQPROPERTYRESTRICTION defines a single property restriction. MQRESTRICTION specifies an array of restrictions as well as a count of how many restrictions there are (see the following examples).
This example locates queues by their type of service. For example, locating all the queues whose PROPID_Q_TYPE equals guidx.
/*Set property restriction. */
MQPROPERTYRESTRICTION PropertyRestriction;
PropertyRestriction.rel = PREQ;
PropertyRestriction.prop = PROPID_Q_TYPE;
PropertyRestriction.prval.vt = VT_CLSID;
PropertyRestriction.prval.puuid = &guidX;
/*Package restrictions. */
MQRESTRICTION rest;
rest.cRes = 1;
rest.paPropRes = &PropertyRestriction;
This example locates queues by their type of service (PROPID_Q_TYPE equals guidx) and by their message journal property (PROPID_Q_JOURNAL equals 1).
First, prepare the property restrictions:
/*Set property restrictions. */
MQPROPERTYRESTRICTION PropertyRestrictions[2];
/*Set first restriction. */
PropertyRestrictions[0].rel = PREQ;
PropertyRestrictions[0].prop = PROPID_Q_TYPE;
PropertyRestrictions[0].prval.vt = VT_CLSID;
PropertyRestrictions[0].prval.puuid = &guidX;
/*Set second restriction. */
PropertyRestrictions[1].rel = PREQ;
PropertyRestrictions[1].prop = PROPID_Q_JOURNAL;
PropertyRestrictions[1].prval.vt = VT_UI1;
PropertyRestrictions[1].prval.bVal = 1;
/*Package the restrictions. */
MQRESTRICTION rest;
rest.cRes = 2;
rest.paPropRes = PropertyRestrictions;
Setting pRestriction to NULL retrieves information about all the queues.
The pColumns parameter allows you to specify which queue properties to retrieve. You can retrieve any number of queue properties with the same call to MQLocateBegin.
The pSort parameter allows you to specify the sort order (ascending or descending) of the result according to one or more of the properties (PROPID_Q_PATHNAME cannot be used as a sort key). Two structures are used to set the sort order: MQSORTKEY specifies a single sort key, and MQSORTSET specifies an array of sort keys along with the number of keys.
For example, the following code sorts queues according to their quota:
/* Prepare sort key. */
MQSORTKEY SortKey;
SortKey.propColumn = PROPID_Q_QUOTA;
SortKey.dwOrder = QUERY_SORTASCEND;
/* Indicate number of sort keys. */
MQSORTSET SortSet;
SortSet.cCol = 1;
SortSet.aCol = &SortKey;
When running a query, MSMQ can locate queues faster when the query is based on PROPID_Q_INSTANCE, PROPID_Q_TYPE, or PROPID_Q_LABEL (PREQ only). The query runs faster because these properties are indexed in Active Directory, providing a faster way for MSMQ to locate the property specified in the call.
MQLocateBegin can only return queues that are in Active Directory when MQLocateBegin is called. Queues added to Active Directory after MQLocateBegin is called are not included.
Public queues cannot be located if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers that are working offline, and MSMQ routing servers (FRS). (For information on offline operations, see MSMQ Offline Support.)
For an example of using MQLocateBegin, see Locating a Public Queue.
Windows NT: Requires version 4.0 SP3 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in mq.h.
Import Library: Use mqrt.lib.
Unicode: Defined only as Unicode.
MQCOLUMNSET, MQLocateEnd, MQLocateNext, MQPROPERTYRESTRICTION, MQRESTRICTION, MQSORTKEY, MQSORTSET, PROPID_Q_JOURNAL, PROPID_Q_LABEL, PROPID_Q_PATHNAME, PROPID_Q_TYPE