PROPID_M_ACKNOWLEDGE

The PROPID_M_ACKNOWLEDGE property specifies the type of acknowledgment messages that MSMQ posts (in the administration queue) when the message is sent.

Type Indicator

VT_UI1 (or VT_NULL)

PROPVARIANT Field

bVal

Property Values

This property can be set to one (or more by ORing them together) of the following values:

MQMSG_ACKNOWLEDGMENT_FULL_REACH_QUEUE

Posts positive and negative acknowledgments depending on whether or not the message reaches the queue. This can happen when the time-to-reach-queue timer expires, or a message cannot be authenticated.

MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE

Posts a positive or negative acknowledgment depending on whether or not the message is retrieved from the queue before its time-to-be-received timer expires.

MQMSG_ACKNOWLEDGMENT_NACK_REACH_QUEUE

Posts a negative acknowledgment when the message cannot reach the queue. This can happen when the time-to-reach-queue timer expires, or a message cannot be authenticated.

MQMSG_ACKNOWLEDGMENT_NACK_RECEIVE

Posts a negative acknowledgment when an error occurs and the message cannot be retrieved from the queue before its time-to-be-received timer expires.

MQMSG_ACKNOWLEDGMENT_NONE

The default. No acknowledgment messages (positive or negative) are posted.

Remarks

Positive and negative acknowledgments are typically MSMQ-generated messages that are sent to an administration queue specified by the message (acknowledgment messages can also be created by MSMQ connector applications when sending messages to a foreign queue). When asking for acknowledgments, you must also specify the administration queue when you send the message (see PROPID_M_ADMIN_QUEUE). For information on administration queues, see Administration Queues.

Acknowledgment messages contain some of the information found in the original message, however, each acknowledgment message has its own message identifier and class. The message identifier, PROPID_M_MSGID, identifies the acknowledgment in the same way it identifies each message sent by an MSMQ application. The message class, PROPID_M_CLASS, identifies the type of acknowledgment that was posted. Both these properties are set by MSMQ when it creates the acknowledgment message.

To request acknowledgment messages, pass PROPID_M_ACKNOWLEDGE and PROPID_M_ADMIN_QUEUE to MQSendMessage.

To find out if an acknowledgment message was requested for a message in a queue, pass PROPID_M_ACKNOWLEDGE to MQReceiveMessage and examine its returned value. When passing PROPID_M_ACKNOWLEDGE to MQReceiveMessage, the corresponding VT field in the aPropVar array can be set to VT_NULL.

For information on the time-to-reach-queue and time-to-be-received timers, see Message Timers. To set the time-to-reach-queue and time-to-be-received timers, set PROPID_M_TIME_TO_REACH_QUEUE and PROPID_M_TIME_TO_BE_RECEIVED, respectively.

To see how PROPID_M_ACKNOWLEDGE is used when sending messages, see Sending Messages that Request Acknowledgments.

Example

The following example sets PROPID_M_ACKNOWLEDGE and PROPID_M_ADMIN_QUEUE as part of preparing MQMSGPROPS.

MQMSGPROPS MsgProps;
PROPVARIANT aVariant[10];
MSGPROPID aPropId[10];
DWORD PropIdCount = 0;

HRESULT hr;

QUEUEHANDLE hQueue;

//
// Set PROPID_M_ACKNOWLEDGE.
//
aPropId[PropIdCount] = PROPID_M_ACKNOWLEDGE;           //PropId
aVariant[PropIdCount].vt = VT_UI1;                     //Type
aVariant[PropIdCount].bVal = MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE; //Value

PropIdCount++;

//
// Set the PROPID_M_ADMIN_QUEUE property.
//
aPropId[PropIdCount] = PROPID_M_ADMIN_QUEUE;         //PropId
aVariant[PropIdCount].vt = VT_LPWSTR;                //Type
aVariant[PropIdCount].pwszVal = szwAdminFormatName;  //An already obtained format name of the admin queue.

PropIdCount++;

//
// Set other message properties such as PROPID_M_BODY, PROPID_M_LABEL.
//



//
// Set the MQMSGPROPS structure
//
MsgProps.cProp = PropIdCount;       //Number of properties.
MsgProps.aPropID = aPropId;         //Ids of properties.
MsgProps.aPropVar = aVariant;       //Values of properties.
MsgProps.aStatus  = NULL;           //No Error report.
 



//
// Send message.
//
hr = MQSendMessage(
     hQueue,                  // handle to the Queue.
     &MsgProps,               // Message properties to be sent.
     MQ_NO_TRANSACTION        // No transaction
     );

if (FAILED(hr))
   {
    //
    // Handle error condition
    //
    }
 

See Also

PROPID_M_ADMIN_QUEUE, PROPID_M_CLASS, PROPID_M_MSGID, PROPID_M_TIME_TO_BE_RECEIVED, PROPID_M_TIME_TO_REACH_QUEUE

© 1997 by Microsoft Corporation. All rights reserved.