MSMQQuery.LookupQueue

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 LookupQueue method of the MSMQQuery object creates, initializes, and returns an MSMQQueueInfos object that defines a query for locating a collection of public queues based on the following queue properties: queue identifier, service type, label, creation time, modification time, and multicast address.

Function LookupQueue( _  
  [ ByRef QueueGuid As Variant ], _  
  [ ByRef ServiceTypeGuid As Variant ], _  
  [ ByRef Label As Variant ], _  
  [ ByRef CreateTime As Variant ], _  
  [ ByRef ModifyTime As Variant ], _  
  [ ByRef RelServiceType As Variant ], _  
  [ ByRef RelLabel As Variant ], _  
  [ ByRef RelCreateTime As Variant ], _  
  [ ByRef RelModifyTime As Variant ], _  
  [ ByRef MulticastAddress As Variant ], _  
  [ ByRef RelMulticastAddress As Variant ] _  
  ) As MSMQQueueInfos  

Parameters

QueueGuid

[in, optional] Identifier of the queue (in C++, a reference to a VARIANT containing a BSTR that specifies the queue identifier in GUID format with the braces normally used with GUIDs).

ServiceTypeGuid

[in, optional] Type of service provided by the queue (in C++, a reference to a VARIANT containing a BSTR that specifies the service type in GUID format with the braces normally used with GUIDs). See also RelServiceType.

Label

[in, optional] Label of the queue (in C++, a reference to a VARIANT containing a BSTR that specifies the label). See also RelLabel.

CreateTime

[in, optional] Time when the queue was created (in C++, a reference to a VARIANT containing a DATE that specifies the date and time when the queue was created). See also RelCreateTime.

ModifyTime

[in, optional] Time when the queue properties were last set, either when the queue was created or the last time when MSMQQueueInfo.Update was called (in C++, a reference to a VARIANT containing a DATE that specifies the applicable date and time). See also RelModifyTime.

RelServiceType

[in, optional] Relationship parameter for ServiceTypeGuid (in C++, a reference to a VARIANT that specifies the relationship parameter). The default is REL_EQ.

RelLabel

[in, optional] Relationship parameter for Label (in C++, a reference to a VARIANT that specifies the relationship parameter). The default is REL_EQ.

RelCreateTime

[in, optional] Relationship parameter for CreateTime (in C++, a reference to a VARIANT that specifies the relationship parameter). The default is REL_EQ.

RelModifyTime

[in, optional] Relationship parameter for ModifyTime (in C++, a reference to a VARIANT that specifies the relationship parameter). The default is REL_EQ.

MulticastAddress

[in, optional] Multicast address associated with the queue (in C++, a reference to a VARIANT containing a BSTR that specifies the multicast address). If this parameter is specified with an empty string, Message Queuing returns all queues that are not associated with any multicast address. See also RelMulticastAddress.

RelMulticastAddress

[in, optional] Relationship parameter for MulticastAddress (in C++, a reference to a VARIANT that specifies the relationship parameter). The default is REL_EQ.

Return Values

An MSMQQueueInfos object that defines a query for locating a collection of public queues (in C++, a smart pointer to the IMSMQQueueInfos interface).

Error Codes

For information on return codes, see Message Queuing Error and Information Codes.

Remarks

LookupQueue returns a single MSMQQueueInfos object that represents the search criteria for locating a set of MSMQQueueInfo objects, each containing information describing a single public queue.

The relationship parameters RelServiceType, RelLabel, RelCreateTime, RelModifyTime, and RelMulticastAddress may be set to simple Boolean comparison operators that can be used in conjunction with the values set in the respective lookup parameters. These comparison operators include: equal to (REL_EQ), not equal to (REL_NEQ), less than (REL_LT), greater than (REL_GT), less than or equal to (REL_LE), greater than (REL_GE), and REL_NOP (REL_NOP indicates that the associated lookup parameter should be ignored). These operators give you greater control over which queues are returned by the query.

Because these comparison operators are constants defined in Mqoai.h, they must be specified by their numerical values in scripts written using VBScript. The following table lists the numerical value for each constant that specifies a comparison operator.

The CreateTime and ModifyTime parameters return both the date and time. Consequently, using the REL_EQ value for RelCreateTime or RelModifyTime may not prove very useful.

When running a query, Message Queuing can locate queues faster when the query is based on MSMQQueueInfo.QueueGuid, MSMQQueueInfo.ServiceTypeGuid, or MSMQQueueInfo.Label (RelLabel = REL_EQ). The query runs faster because these properties are indexed in the directory service, providing a faster way for Message Queuing to locate the property specified in the call.

LookupQueue can return only those queues that are listed in the directory service when LookupQueue is called. Queues created after LookupQueue is called are not included.

To reference a specific queue in the collection, the application must call the MSMQQueueInfos.Reset and MSMQQueueInfos.Next methods. MSMQQueueInfos.Reset starts a query of the directory service and locates the first public queue satisfying the search criteria. MSMQueueInfos.Next locates the next queue. After a queue is located, the application can call the MSMQQueueInfo.Open method to open the queue.

Although access to the directory service is needed to locate public queues in a query, the Lookup method can create an MSMQueueInfos object on a computer that is running in workgroup mode or is temporarily offline.

In C++ COM applications, you must use a smart pointer to the IMSMQQuery3 interface to expose the LookupQueue method if the optional MulticastAddress and RelMulticastAddress parameters are specified in the call.

Example Code

The following examples are included in Using Message Queuing.

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 Mqoai.h.

Library: Use Mqoa.lib.

See Also

MSMQQueueInfo.Open
MSMQQueueInfos.Next
MSMQQueueInfos.Reset
MSMQQuery