MQLocateNext

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

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[]    
);

Parameters

hEnum

[in] Query handle returned by a previous call to MQLocateBegin.

pcProps

[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.

aPropVar

[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).

Return Values

MQ_OK

Indicates success.

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

The query handle specified in hEnum is not valid.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_RESULT_BUFFER_TOO_SMALL (0xC00E0046)

The supplied buffer for aPropVar is too small. MQLocateNext could not return at least one complete query result.

Note

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.

Remarks

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	Locating Queues Using Function Calls
Structures used to set search criteria	Specifying Search Criteria
Structures used to set returned queue properties	Specifying Queue Properties to Retrieve

Example Code

The following code example is included in Using Message Queuing.

For an example of	See
Locating queues based on queue label	C++ Code Example: Locating a Queue

Requirements

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.