MessageQueue::GetMessageQueueEnumerator Method (MessageQueueCriteria^)
Provides forward-only cursor semantics to enumerate through all public queues on the network that meet the specified criteria.
Assembly: System.Messaging (in System.Messaging.dll)
public: static MessageQueueEnumerator^ GetMessageQueueEnumerator( MessageQueueCriteria^ criteria )
Parameters
- criteria
-
Type:
System.Messaging::MessageQueueCriteria^
A MessageQueueCriteria that contains the criteria used to filter the available message queues.
Return Value
Type: System.Messaging::MessageQueueEnumerator^A MessageQueueEnumerator that provides a dynamic listing of the public message queues on the network that satisfy the restrictions specified by the criteria parameter.
This overload of GetMessageQueueEnumerator returns a listing of all the public queues on the network that satisfy criteria defined in the application criteria. You can specify the criteria to include, for example, queue creation or modification time, computer name, label, category, or any combination of these.
Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue that occurs beyond the cursor's current position. Changes to queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling Reset for the MessageQueueEnumerator.
There is no defined ordering of queues in a network. An enumerator does not order them, for example, by computer, label, public or private status, or any other accessible criteria.
If you want a static snapshot of the queues on the network rather than a dynamic connection to them, specify criteria for GetPublicQueues or call GetPrivateQueuesByMachine(String^). Each of these two methods returns an array of MessageQueue objects, which represent the queues at the time the method was called. Calling GetPublicQueuesByCategory(Guid), GetPublicQueuesByLabel(String^), or GetPublicQueuesByMachine(String^) provides the same results as calling GetPublicQueues with the filtering criteria of Category, Label, and MachineName, respectively.
The following table shows whether this method is available in various Workgroup modes.
Workgroup mode | Available |
|---|---|
Local computer | No |
Local computer and direct format name | No |
Remote computer | No |
Remote computer and direct format name | No |
The following code example iterates through message queues and displays the path of each queue that was created in the last day and that exists on the computer "MyComputer".
#using <system.dll> #using <system.messaging.dll> using namespace System; using namespace System::Messaging; ref class MyNewQueue { public: // Iterates through message queues and displays the // path of each queue that was created in the last // day and that exists on the computer "MyComputer". void ListPublicQueuesByCriteria() { UInt32 numberQueues = 0; // Specify the criteria to filter by. MessageQueueCriteria^ myCriteria = gcnew MessageQueueCriteria; myCriteria->MachineName = "MyComputer"; myCriteria->CreatedAfter = DateTime::Now.Subtract( TimeSpan(1,0,0,0) ); // Get a cursor into the queues on the network. MessageQueueEnumerator^ myQueueEnumerator = MessageQueue::GetMessageQueueEnumerator( myCriteria ); // Move to the next queue and read its path. while ( myQueueEnumerator->MoveNext() ) { // Increase the count if priority is Lowest. Console::WriteLine( myQueueEnumerator->Current->Path ); numberQueues++; } // Handle no queues matching the criteria. if ( numberQueues == 0 ) { Console::WriteLine( "No public queues match criteria." ); } return; } }; int main() { // Create a new instance of the class. MyNewQueue^ myNewQueue = gcnew MyNewQueue; // Output the count of Lowest priority messages. myNewQueue->ListPublicQueuesByCriteria(); return 0; }
Available since 1.1