MSMQQueue.EnableNotification

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The EnableNotification method of the MSMQQueue object 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.

Sub EnableNotification( _  
  ByRef Event As MSMQEvent, _  
  [ ByRef Cursor As Variant ], _  
  [ ByRef ReceiveTimeout As Variant ] _  
  )

Parameters

Event

[in] MSMQEvent object (in C++, a smart pointer to the IMSMQEvent interface).

Cursor

[in, optional] One of the following constants that specifies the type of cursor behavior (in C++, a reference to a VARIANT that specifies the constant).

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, and then notification starts when a message is at the new cursor location.

ReceiveTimeout

[in, optional] The time (in milliseconds) that Message Queuing will wait for a message to arrive (in C++, a reference to a VARIANT containing a LONG that specifies the time). This argument can be set to INFINITE, 0, or a specific amount of time. The default setting is INFINITE.

Return Values

This method has no return values.

Error Codes

For information on return codes, see Message Queuing Error and Information Codes.

Remarks

After EnableNotification is called, an event is triggered when a message is found at the position specified by Cursor. When the default setting is used, an event is triggered when a message is found in the queue.

For information on navigating queues with cursors, see Navigating with Cursors.

EnableNotification fires a single MSMQEvent.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 MSMQQueue object representing the queue where the message arrived must be passed to the MSMQEvent_Arrived event handler (typically implemented by the user). If the Cursor argument is specified, its value must also be passed to the event handler.

Note

In Microsoft® Visual Basic®, the application's event handler can still be invoked even if the form that 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 INFINITE blocks processing until a message is found in the queue (this is the default setting). If ReceiveTimeout is set to "0", an Arrived event is fired if a message is waiting in the queue, or an exception is thrown immediately with the error code MQ_ERROR_IO_TIMEOUT if no message is waiting in the queue. If ReceiveTimeout is set to any other value, an Arrived event is fired when a message is found in the queue, or an exception is thrown with the error code MQ_ERROR_IO_TIMEOUT after ReceiveTimeout elapses and no message is found in the queue.

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

Example Code

The following examples are included in Using Message Queuing.

For an example of	See
Using event notification to read messages in a queue asynchronously	C/C++ COM Code Example: Reading Messages Asynchronously Visual Basic Code Example: Reading Messages Asynchronously

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.