Peek
MSMQQueue

The Peek method returns the first message in the queue, or waits for a message to arrive if the queue is empty. It does not remove the message from the queue.

Syntax

set object2 = object1.Peek ([ReceiveTimeout][, WantDestinationQueue][, WantBody])

Syntax Element	Description
object1	Queue (MSMQQueue) object that represents the queue where the message resides.
object2	Message (MSMQMessage) object that represents the message read from the queue.
ReceiveTimeout	Optional. Specifies how long (in milliseconds) MSMQ waits for a message to arrive.
WantDestinationQueue	Optional (default is FALSE). If TRUE, DestinationQueueInfo is updated when the message is read from the queue. Setting this property to TRUE may slow down the operation of the application.
WantBody	Optional (default is TRUE). If the Body of the message is not needed, set this property to FALSE to optimize the speed of the application.

Return Values

MSMQMessage object.

Remarks

The Peek method always looks at the first message in the queue. It is completely independent of the implied cursor used by PeekCurrent, PeekNext, and ReceiveCurrent.

Applications can peek at messages in queues opened with peek or receive access (see Open).

The ReceiveTimeout parameter can be used to control how long MSMQ waits for a message to arrive when the queue is empty.

The WantDestinationQueue and WantBody parameters can be used to optimize the speed of the application.

Example

This example sends a message to the destination queue to make sure at least one message is there, and then reads the first message in the queue. If another message is already in the queue, the message returned by Peek may not be the message sent by the example.

To try this example using Microsoft Visual Basic (version 5.0), paste the code into the Code window of a form, run the example, and click the form.

Option Explicit

Dim query As New MSMQQuery
Dim qinfoDest As MSMQQueueInfo
Dim qDest As MSMQQueue
Dim msgSent As New MSMQMessage
Dim msgDest As MSMQMessage

Private Sub Form_Click()
            
   '***************************
   ' Locate destination queue
   '(create one if one doesn't
   ' exist).
   '***************************
   Set qinfos = query.LookupQueue(Label:="Destination Queue")
   qinfos.Reset
   Set qinfoDest = qinfos.Next
   If qinfoDest Is Nothing Then
      Set qinfoDest = New MSMQQueueInfo
      qinfoDest.PathName = ".\DestQueue"
      qinfoDest.Label = "Destination Queue"
      qinfoDest.Create
   End If
   
   '**************
   ' Open destination queue.
   '**************
   Set qDest = qinfoDest.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
   
   '**************
   ' Send Message.
   '**************
   msgSent.Label = "Test Message"
   msgSent.Body = "This message is used to test reading messages."
   
   msgSent.Send qDest
   qDest.Close
  
   '**********************
   ' PEEK at first message
   ' in the queue.
   '**********************
   
   Set qDest = qinfoDest.Open(MQ_PEEK_ACCESS, MQ_DENY_NONE)
      
   On Error GoTo Handler
   Set msgDest = qDest.Peek(ReceiveTimeout:=100)
   MsgBox "The first message in the queue is: " + msgDest.Label
   Exit Sub
   
   '***************
   ' Error Handler
   '***************
   
Handler:
   'Test for errors.

End Sub

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mqoai.h.
  Import Library: Use mqoa.lib.
  Unicode: Defined only as Unicode.