Reading Messages

MSMQ messages can be read from a queue either synchronously or asynchronously. In addition, they can be read within a transaction (for information on reading messages in transactions, see MSMQ Transactions).

When an application synchronously reads messages in a queue, all calls are blocked until the next message is available or a specific amount of time expires. The amount of time the application waits can be 0, a specific amount of time (in milliseconds), or the maximum time allowed by your MSMQ enterprise. When the time expires for a synchronous read, MSMQ returns a NULL message (for applications using ActiveX components) or an MQ_ERROR_IO_TIMEOUT error (for applications using API functions).

There are four ways to receive messages asynchronously:

• Use a callback function.
• Use a Windows Event mechanism.
• Use a Windows NT completion port.
• Use the MSMQ ActiveX components, defining an event handler that is notified when a message arrives or a time-out occurs. ActiveX components return MQ_ERROR_IO_TIMEOUT when a time-out occurs.

When using a callback function, MSMQ reads the message by calling the callback function that is currently registered. The function is called if a message is immediately available, when the message arrives, or when the time expires.

When using an event mechanism, an OVERLAPPED structure provides a valid handle (hEvent field) to an event object. When a suitable message arrives, or a time-out occurs, the event object is set to the signaled state. For more information on OVERLAPPED structures, see the Platform SDK.

When using a Windows NT® completion port, a queue handle can be associated with the port to receive messages asynchronously. For more information, see CreateIOCompletionPort in the Microsoft Platform SDK.

When reading messages in a queue, MSMQ can peek at the messages (leaving them in the queue) or retrieve them (removing the messages from the queue).