The MQLocateNext function retrieves the requested queue information from the query. It is called after obtaining a query handle from a previous call to MQLocateBegin.
HRESULT APIENTRY MQLocateNext( HANDLE hEnum, DWORD * pcProps, MQPROPVARIANT aPropVar );
[in] Query handle returned by a previous call to MQLocateBegin.
[in, out] On input, a pointer to a variable that specifies the number of elements in the aPropVar array.
On return, pcProps holds the number of properties returned to the query. MQLocateNext returns as many completed sets of properties (the number of properties returned for each queue) as possible. A returned value of 0 indicates no queues were found.
[out] Holds the values of the retrieved properties in an array of MQPROPVARIANT. For each property returned, MQLocateNext sets the vt field and the corresponding union member of the appropriate aPropVar element. MQFreeMemory must be called to free memory allocated by Message Queuing, which happens when an MQPROPVARIANT element requires the allocation of memory (for example, for LPWSTR and CLSID).
The query handle specified in hEnum is not valid.
A connection with the directory service cannot be established. Verify permissions for accessing the directory service.
The supplied buffer for aPropVar is too small. MQLocateNext could not return at least one complete query result.
|Apart from generic Message Queuing error codes, this function may return ADSI and LDAP error codes. For example, LDAP_BUSY (0x8007200E) is returned when the directory service server is busy.|
The MQLocateNext function is called after obtaining a query handle from a previous call to MQLocateBegin. The call can be repeated, using the same query handle, until all the results of the query are received (until pcProps is 0). For a complete description of running a query, see Locating Queues.
The MQLocateNext function returns as many completed results (the number of properties requested in MQLocateBegin) as possible. Consequently, you should always specify a multiple of the number of requested properties when setting pcProps. By using a multiple of the requested properties, allocated space for these properties is not wasted.
Message Queuing returns information only for those queues whose access rights for the calling application include the right to retrieve the queue properties (MQSEC_GET_QUEUE_PROPERTIES). For information on access rights see, Access Control.
MQLocateBegin cannot locate public queues if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers that are working offline, and Message Queuing routing servers (FRS).
For information on offline operations, see Message Queuing Offline Support.
|For information on||See|
What information Message Queuing needs to locate queues
Structures used to set search criteria
Structures used to set returned queue properties
The following code example is included in Using Message Queuing.
|For an example of||See|
Locating queues based on queue label
Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Mq.h.
Library: Use Mqrt.lib.