MessageQueue.Peek Method (TimeSpan)
Returns without removing (peeks) the first message in the queue referenced by this MessageQueue. The Peek method is synchronous, so it blocks the current thread until a message becomes available or the specified time-out occurs.
Namespace: System.Messaging
Assembly: System.Messaging (in System.Messaging.dll)
Parameters
- timeout
- Type: System.TimeSpan
A TimeSpan that indicates the maximum time to wait for the queue to contain a message.
Return Value
Type: System.Messaging.MessageThe Message that represents the first message in the queue.
| Exception | Condition |
|---|---|
| ArgumentException | The value specified for the timeout parameter is not valid, possibly timeout is less than TimeSpan.Zero or greater than MessageQueue.InfiniteTimeout. |
| MessageQueueException | An error occurred when accessing a Message Queuing method. |
Use this overload to peek a queue, or to wait a specified period of time until a message exists in the queue. The method returns immediately if a message already exists in the queue.
The Peek method reads, but does not remove, the first message from the queue. Therefore, repeated calls to Peek return the same message, unless a higher priority message arrives in the queue. The Receive method, on the other hand, both reads and removes the first message from the queue. Repeated calls to Receive, therefore, return different messages.
Message Queuing orders messages in the queue according to priority and arrival time. A newer message is placed before an older one only if it is of a higher priority.
Use Peek when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked up to the specified period of time, or indefinitely if you indicated InfiniteTimeout. If you need the application processing to continue without waiting, use the asynchronous BeginPeek method.
The following table shows whether this method is available in various Workgroup modes.
Workgroup mode | Available |
|---|---|
Local computer | Yes |
Local computer and direct format name | Yes |
Remote computer | No |
Remote computer and direct format name | Yes |
The following code example uses the Peek method with a time-out of zero to check whether the queue is empty.
using System; using System.Messaging; namespace MyProject { /// <summary> /// Provides a container class for the example. /// </summary> public class MyNewQueue { //************************************************** // Provides an entry point into the application. // // This example determines whether a queue is empty. //************************************************** public static void Main() { // Create a new instance of the class. MyNewQueue myNewQueue = new MyNewQueue(); // Determine whether a queue is empty. bool isQueueEmpty = myNewQueue.IsQueueEmpty(); return; } //************************************************** // Determines whether a queue is empty. The Peek() // method throws an exception if there is no message // in the queue. This method handles that exception // by returning true to the calling method. //************************************************** public bool IsQueueEmpty() { bool isQueueEmpty = false; // Connect to a queue. MessageQueue myQueue = new MessageQueue(".\\myQueue"); try { // Set Peek to return immediately. myQueue.Peek(new TimeSpan(0)); // If an IOTimeout was not thrown, there is a message // in the queue. isQueueEmpty = false; } catch(MessageQueueException e) { if (e.MessageQueueErrorCode == MessageQueueErrorCode.IOTimeout) { // No message was in the queue. isQueueEmpty = true; } // Handle other sources of MessageQueueException. } // Handle other exceptions as necessary. // Return true if there are no messages in the queue. return isQueueEmpty; } } }
- Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.
Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.