MQLocateNext

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,         
  PROPVARIANT 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 PROPVARIANT. 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 MSMQ, which happens when a PROPVARIANT element involves allocation of memory (for example lpwstr, GUID).

Return Values

MQ_OK: Indicates success.
MQ_ERROR_INVALID_HANDLE: The query handle specified in hEnum is not valid.
MQ_ERROR_NO_DS: Cannot access Active Directory.
MQ_ERROR_RESULT_BUFFER_TOO_SMALL: The supplied buffer for aPropVar is too small. MQLocateNext could not return at least one complete query result.

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 a Public Queue.

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.

MSMQ only returns information for those queues that the calling application has access rights (MQSEC_GET_QUEUE_PROPERTIES) to.

MQLocateNext is not supported if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers (working offline), and MSMQ routing servers (FRS). (For information on offline operations, see MSMQ Offline Support.)

Examples

For an example of using MQLocateNext, see Locating a Public Queue.

QuickInfo