PROPID_M_TIME_TO_BE_RECEIVED

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_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.

Property ID

PROPID_M_TIME_TO_BE_RECEIVED

Type Indicator

VT_UI4

MQPROPVARIANT Field

ulVal

Property Value

Integer value (the default is INFINITE).

Remarks

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.

To set the time interval for the time-to-be-received timer, specify PROPID_M_TIME_TO_BE_RECEIVED in the MQMSGPROPS structure and call MQSendMessage.

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

Example Code

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.

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.

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_ACKNOWLEDGE
PROPID_M_JOURNAL
PROPID_M_TIME_TO_REACH_QUEUE