The PROPID_M_TIME_TO_BE_RECEIVED property specifies the total time (in seconds) that the message is allowed to live. This includes the time it spends getting to the destination queue plus the time spent waiting in the queue before it is retrieved by an application.
Integer value (the default is INFINITE).
PROPID_M_TIME_TO_BE_RECEIVED is used to set the time-to-be-received timer. If the time elapses before the message is removed from the queue, Message Queuing discards the message, sending it to the dead-letter queue if the PROPID_M_JOURNAL property of the message is set to MQMSG_DEADLETTER. For a discussion of message timers, see Message Timers.
Message Queuing can also send a return negative acknowledgment message back to the sending application if the message is not removed in time and the PROPID_M_ACKNOWLEDGE property of the message is set accordingly.
In each hop, Message Queuing subtracts the time elapsed on the applicable computer from the value of PROPID_M_TIME_TO_BE_RECEIVED when it dispatches the message to the next computer, where a new timer is set. To find out how much time remains in the time-to-be-received timer when the message is received, specify PROPID_M_TIME_TO_BE_RECEIVED in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned value.
If the time-to-be-received and time-to-reach-queue timers are both set, the time-to-be-received timer takes precedence over the time-to-reach-queue timer.
When several messages are sent in a transaction, Message Queuing uses the time-to-be-received timer of the first message. For more information, see Message Queuing Transactions.
When Message Queuing creates an acknowledgment message, it always sets the PROPID_M_TIME_TO_BE_RECEIVED property of the message to INFINITE.
When a message is sent from an independent client computer, the time-to-be-received timer starts ticking as soon as the send operation of the sending application succeeds, even if the client computer is offline.
When using dependent clients, make sure that the clock on the client computer is in sync with the clock on the supporting server. If these two clocks are not synchronized, you may see unpredictable behavior when sending messages with a time-to-be-received timer set.
When a message is sent over an HTTP transport, the relative time specified in the PROPID_M_TIME_TO_BE_RECEIVED property of the message is converted to the absolute UTC date and time until which the message may be stored in the destination queue and is inserted into the <TTrq> element in the header portion of the SOAP envelope. For more information on the <TTrq> element of an HTTP message, see Properties Mapped to Elements of the MSMQ Namespace.
Equivalent COM Property
With COM components, the equivalent property is MSMQMessage.MaxTimeToReceive.
The following code fragments show how PROPID_M_TIME_TO_BE_RECEIVED is specified in arrays that can be used to initialize an MQMSGPROPS structure for setting the time-to-be-received timer and for retrieving the remaining time.
|The timer is set to expire in three minutes.|
To Set PROPID_M_TIME_TO_BE_RECEIVED
aMsgPropId[i] = PROPID_M_TIME_TO_BE_RECEIVED; aMsgPropVar[i].vt = VT_UI4; aMsgPropVar[i].ulVal = 60*3; i++;
To Retrieve PROPID_M_TIME_TO_BE_RECEIVED
aMsgPropId[i] = PROPID_M_TIME_TO_BE_RECEIVED; aMsgPropVar[i].vt = VT_UI4; i++;
The following example is included in Using Message Queuing.
|For an example of||See|
Using the time-to-be-received timer to generate acknowledgment messages