Export (0) Print
Expand All

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)

public Message Peek(
	TimeSpan timeout
)

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.Message
The Message that represents the first message in the queue.

ExceptionCondition
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;

		}
	}
}

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, 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.

Show:
© 2014 Microsoft