Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/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 MSMQEventobject.

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.EnableNotificationis 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.EnableNotificationfires a single MSMQEvent.Arrivedevent when it finds a message. To read more messages, MSMQQueue.EnableNotificationmust be explicitly called again from within the event handler.

The Arrived event

The Arrived event is triggered on the MSMQEventobject 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 Arrivedevent 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 EnableNotificationwith ReceiveTimeoutset to infinite (-1) blocks processing until a message is in the queue.

If ReceiveTimeoutis set to 0, an Arrivedevent is fired if a message is in the queue, or an ArrivedErrorevent is fired immediately returning an MQ_ERROR_IO_TIMEOUT error.

Receive errors

Receive errors, such as time-out errors, trigger an MSMQEvent.ArrivedErrorevent on the associated MSMQEventobject.

Requirements

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

See Also