MQCreateCursor

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 MQCreateCursor function creates a cursor for a specific queue and returns a handle to the cursor. This cursor is used to maintain a specific location in a queue when reading the queue's messages.

HRESULT APIENTRY MQCreateCursor(  
  QUEUEHANDLE hQueue,    
  PHANDLE phCursor       
);

Parameters

hQueue

[in] A handle to the queue for which you want to create a cursor.

phCursor

[out] A pointer to a variable that receives the resulting cursor handle.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

The queue handle specified in hQueue is not valid.

MQ_ERROR_INSUFFICIENT_RESOURCES (0xC00E0027)

There are not enough resources to create a new cursor.

MQ_ERROR_REMOTE_MACHINE_NOT_AVAILABLE (0xC00E0069)

The remote computer that hosts the queue for which the cursor is being created is not available.

MQ_ERROR_STALE_HANDLE (0xC00E0056)

The specified queue handle was obtained in a previous session of the queue manager service. Close the queue and open it again to obtain a fresh handle.

Remarks

The MQCreateCursor function is used with MQReceiveMessage when you need to read messages that are not at the front of the queue. Cursors do not need to be used to read only the first message in a queue. For information about how cursors behave when navigating queues, see Navigating with Cursors.

This includes reading messages synchronously or asynchronously.

Note

When reading messages within a transaction, Message Queuing does not roll back cursor movement if the transaction is aborted. For example, given a queue with two messages A1 and A2, if you remove message A1 while in a transaction, Message Queuing will move the cursor to the next message A2. However, if the transaction is aborted for any reason, message A1 is inserted back into the queue, but the cursor will remain pointing at message A2.

To close the cursor, call MQCloseCursor.

Equivalent COM Method

When an application uses the COM components provided by Message Queuing, a cursor is automatically created each time a queue is opened to receive or peek at messages.

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Peeking at each message in a queue using cursors	C/C++ Code Example: Navigating Using Cursors
Filtering specific messages using cursors	C/C++ Code Example: Application-Specific Filters C/C++ Code Example: Correlation Identifier Filters C/C++ Code Example: Time Sent Filters

The following sample shows how to create a cursor from a subqueue.

HANDLE hQueue = NULL;  
LCWSTR wszRejectedOrdersQueue =   
                                 ”DIRECT=OS:mymachine\private$\orders;rejectedorders”;  
hr = MQOpenQueue(wszRejectedOrdersQueue, MQ_RECEIVE_ACCESS,  
                                                         MQ_DENY_RECEIVE_SHARE, &hQueue);  
if (FAILED(hr))  
{  
    return hr;  
}  
  
// Create the cursor used to navigate through the queue.  
hr = MQCreateCursor(hQueue, &hCursor);  
if (FAILED(hr))  
{  
    MQCloseQueue(hQueue);  
    return hr;  
}  
// Peek at the first message in the queue.  
hr = MQReceiveMessage(hQueue, 0, MQ_ACTION_PEEK_CURRENT, &msgprops,   
                                                NULL, NULL, hCursor, MQ_NO_TRANSACTION);  
if (FAILED(hr))  
{  
    MQCloseCursor(hCursor);  
    MQCloseQueue(hQueue);  
    return hr;  
}

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 Mq.h.

Library: Use Mqrt.lib.

Share via