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 an 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

No connection with the Site Controller server. Cannot access the MQIS.

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 for offline operations. For information on offline operations, see MSMQ Offline Support.

Examples

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

See Also

MQFreeMemory, MQGetQueueProperties, MQLocateBegin, MQLocateEnd, MQSetQueueSecurity

© 1997 by Microsoft Corporation. All rights reserved.