MSMQQueue.EnableNotification
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 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 |
| Windows Mobile | Windows Mobile Version 5.0 and later |