The EnableNotification method starts event notification for asynchronously reading messages in the queue. Once this method is called, applications can asynchronously peek at messages or retrieve them from the queue in a user-defined event handler.
object.EnableNotification (Event[, Cursor][,ReceiveTimeout])
| Syntax Element | Description |
|---|---|
| object | Queue (MSMQQueue) object that represents the open instance of the queue. |
| Event | References an MSMQEvent object. |
| Cursor | Optional. Specifies the action of the cursor. 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) MSMQ waits for a message to arrive. |
For information on return codes, see MSMQ Error and Information Codes.
When 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.
EnableNotification fires a single Arrived event when it finds a message. To read more messages, EnableNotification must be explicitly called again from within the event handler.
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.
Note In Microsoft® Visual Basic®, the application's event handler can still be invoked even if the form it is on has been unloaded by the application. When the event handler is fired, Visual Basic reloads the form automatically if any of its members (for example, a message box on the form) are referred to.
When an Arrived event is triggered, there is no guarantee that the message that triggered the event will still be available when the application tries to use the message. All queues are dynamic, and other clients may 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.)
Invoking EnableNotification with ReceiveTimeout set to 0 is similar to synchronously calling Peek.
Receive errors (such as time-out errors) trigger an ArrivedError event on the associated MSMQEvent object.
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.