MSMQQueue.EnableNotification (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

This method starts event notification for asynchronously reading messages in the queue. When this method is called, applications can asynchronously peek at messages or retrieve them from the queue in a user-defined event handler.

Syntax

HRESULT EnableNotification( 
  MSMQEvent* Event,
  VARIANT* Cursor, 
  VARIANT* ReceiveTimeout 
);

Parameters

Event
References an MSMQEvent object.

Cursor
Optional. Specifies the action of the cursor. The following table shows the possible values.

Flag	Description
MQMSG_FIRST	Default. Notification starts when a message is in the queue.
MQMSG_CURRENT	Notification starts when a message is at the current location of the cursor.
MQMSG_NEXT	The cursor is moved, then notification starts when a message is at the new cursor location.

ReceiveTimeout
Optional. Specifies how long, in milliseconds, Message Queuing waits for a message to arrive.

This parameter can be set to infinite (-1), 0, or a specific amount of time.

The default setting is infinite.

Return Value

The following table describes the common return values.

Value	Description
S_OK	Success
E_INVALIDARG	One or more arguments are invalid
E_NOTIMPL	The function contains no implementation
E_OUTOFMEMORY	Out of memory

Remarks

When MSMQQueue.EnableNotification is called, events are triggered when a message is found at the position specified by Cursor. When the default setting is used, events are triggered when a message is in the queue.

MSMQQueue.EnableNotification fires a single MSMQEvent.Arrived event when it finds a message. To read more messages, MSMQQueue.EnableNotification must be explicitly called again from within the event handler.

The Arrived event

The Arrived event is triggered on the MSMQEvent object passed in Event. The MSMQEvent_Arrived event handler (typically implemented by the user) is passed a reference to the queue where the message arrived.

When an Arrived event is triggered, there is no guarantee that the message that triggered the event will be available when the application tries to use the message. All queues are dynamic, and other clients might remove the arrived message before it can be used.

It is up to the application to determine if the message is there before attempting to peek at the message or retrieve it. If the queue is not being shared, it is safe to assume that the message is still there.

Setting the ReceiveTimeout parameter to zero

Invoking EnableNotification with ReceiveTimeout set to infinite (-1) blocks processing until a message is in the queue.

If ReceiveTimeout is set to 0, an Arrived event is fired if a message is in the queue, or an ArrivedError event is fired immediately returning an MQ_ERROR_IO_TIMEOUT error.

Receive errors

Receive errors, such as time-out errors, trigger an MSMQEvent.ArrivedError event on the associated MSMQEvent object.

Requirements

Header	mqoai.h
Library	mqoa.lib
Windows Embedded CE	Windows CE .NET 4.0 and later

Partager via