PROPID_M_ACKNOWLEDGE

  • Article

 

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 PROPID_M_ACKNOWLEDGE property specifies the type of acknowledgment messages that Message Queuing will post (in the administration queue) when acknowledgments are requested.

Property ID

PROPID_M_ACKNOWLEDGE

Type Indicator

VT_UI1

MQPROPVARIANT Field

bVal

Property Value

The MQPROPVARIANT field can be set to one or more (with the OR operator) of the following values:

MQMSG_ACKNOWLEDGMENT_FULL_REACH_QUEUE

Posts a positive or negative acknowledgment depending on whether or not the message reaches the queue.

A negative acknowledgment is posted when the time-to-reach-queue timer of the message expires, or when Message Queuing does not deliver the message to the queue for security reasons. These security reasons can include denied send access to the sending application, not being able to authenticate a message, as well as the queue not being able to accept encrypted messages.

MQMSG_ACKNOWLEDGMENT_NACK_REACH_QUEUE

Posts a negative acknowledgment when the message cannot reach the queue.

A negative acknowledgment is posted when the time-to-reach-queue timer of the message expires, or when Message Queuing does not deliver the message to the queue for security reasons. These security reasons can include denied send access to the sending application, not being able to authenticate a message, as well as the queue not being able to accept encrypted messages.

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_RECEIVE

Posts a negative acknowledgment when the message cannot be retrieved from the queue before the message's time-to-be-received timer expires.

MQMSG_ACKNOWLEDGMENT_NONE

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

Remarks

When asking for acknowledgments, you must also specify the administration queue where the acknowledgment messages will be sent.

To request acknowledgment messages, specify PROPID_M_ACKNOWLEDGE and PROPID_M_ADMIN_QUEUE in the MQMSGPROPS structure and call MQSendMessage.

To find out if an acknowledgment message was requested for a message in a queue, specify PROPID_M_ACKNOWLEDGE in the MQMSGPROPS structure. Then, call MQReceiveMessage or MQReceiveMessageByLookupId and examine its returned value. When retrieving this property, the type indicator can be set to VT_UI1 or VT_NULL. If you set the type indicator to VT_NULL, Message Queuing automatically changes the type indicator to VT_UI1 during the function call.

To receive a positive acknowledgment message when a message reaches its destination and when the message is retrieved, the following two full-acknowledgment settings must be combined using the OR operator: MQMSG_FULL_REACH_QUEUE and MQMSG_FULL_RECEIVE.

Acknowledgment messages are typically Message Queuing-generated messages, however they can also be created by connector applications when messages are to a foreign queue.

Equivalent COM Property

With COM components, the equivalent property for setting and retrieving the acknowledgment level is MSMQMessage.Ack.

For information on See
The purpose and content of acknowledgment messages Acknowledgment Messages
The type of queues used as administration queues Administration Queues
The time-to-reach-queue and time-to-be-received timers Message Timers

Example Code

The following code fragment shows how PROPID_M_ACKNOWLEDGE is specified in arrays that can be used to initialize an MQMSGPROPS structure to request a positive or negative receive acknowledgment message.

aMsgPropId[i] = PROPID_M_ACKNOWLEDGE;                     // Property ID  
aMsgPropVar[i].vt = VT_UI1;                               // Type indicator  
aMsgPropVar[i].bVal = MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE;  
i++;

The following example is included in Using Message Queuing.

For an example of See
Sending a message that requests an acknowledgment from Message Queuing C/C++ Code Example: Requesting Acknowledgment Messages

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_ADMIN_QUEUE
PROPID_M_TIME_TO_BE_RECEIVED
PROPID_M_TIME_TO_REACH_QUEUE