Properties Mapped to SRMP Elements

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 header portion of the SOAP envelope in an HTTP message must contain a <properties> entry and may contain <services>, <Stream>, <streamReceipt>, <deliveryReceipt>, and <commitmentReceipt> entries from the SRMP namespace.

Elements of the <properties> Entry

Two Message Queuing message properties are mapped to the following SRMP elements of the mandatory <properties> header entry:

• <expiresAt>

  (Required, read/write.) Specifies the expiration date and time of the message, after which the HTTP message is considered to have expired and must not be processed by the destination message processor (the absolute UTC date and time calculated from the relative time that the message has to reach the queue specified in PROPID_M_TIME_TO_REACH_QUEUE or MSMQMessage.MaxTimeToReachQueue). The string included in this element specifies the date and time in the form yyyymmddTseconds.

• <sentAt>

  (Required, read-only.) Specifies the absolute UTC date and time when the first attempt to transmit the message occurred (PROPID_M_SENTTIME or MSMQMessage.SentTime). The string included in this element specifies the date and time in the form yyyymmddTseconds.

  The recipient SRMP processor must understand and process the <properties> entry and all of its contents for the successful processing of an HTTP message. The encoding of the <properties> element must always contain the attribute se:mustUnderstand="1" to ensure this.

  Note

  The namespace prefix attached to this attribute (se) refers to the SOAP envelope namespace, which is declared as the first attribute in the <Envelope> element. The default namespace for the <properties> element is declared as the second attribute in the <Envelope> entry.

  The following example shows how these properties are included in an HTTP message as elements of the <properties> header entry:

  <properties se:mustUnderstand="1">  
    <expiresAt>20010829T162432</expiresAt>  
    <sentAt>20010829T160432</sentAt>  
  </properties>  
  

Elements of the <services> Entry

Four Message Queuing message properties are mapped to the following six SRMP elements and subelements of the optional <services> header entry:

• <durable/>

  (Optional, read/write.) Specifies the recoverable delivery mechanism. (PROPID_M_DELIVERY or MSMQMessage.Delivery set to MSG_DELIVERY_RECOVERABLE). Message Queuing always sets the delivery mechanism of transactional messages to recoverable.

• <deliveryReceiptRequest>

  (Optional, read/write.) Requests that a receipt or acknowledgment message be sent when the message reaches the destination queue (PROPID_M_ACKNOWLEDGE or MSMQMessage.Ack set to MQMSG_ACKNOWLEDGMENT_FULL_REACH_QUEUE). This element must contain exactly one <sendTo> subelement.

  The following lines provide a complete example of a <deliveryReceiptRequest> entry:

  <deliveryReceiptRequest>  
    <sendTo>  
      http://www.northwindtraders.com/msmq/PRIVATE$/AdminQueue   
    </sendTo>  
  </deliveryReceiptRequest>  
  

• <commitmentReceiptRequest>

  (Optional, read/write.) Requests that a receipt or acknowledgment message be sent when the message is received from the destination queue (PROPID_M_ACKNOWLEDGE or MSMQMessage.Ack set to MQMSG_ACKNOWLEDGMENT_NACK_RECEIVE when a <negativeOnly/> subelement is included, or to MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE when both a <positiveOnly/> subelement and a <negativeOnly/> subelement are included). This element must contain exactly one <sendTo> subelement, may contain a <negativeOnly/> subelement, and may contain both a <negativeOnly/> subelement and a <positiveOnly/> subelement.

  The following lines provide a complete example of a <commitmentReceiptRequest> entry, which requests a positive or negative acknowledgment, depending on whether or not the message is retrieved from the queue before the date and time specified in the <TTrq> element of the <Msmq> entry, that is, before expiration of the message's time-to-be-received timer.

  <commitmentReceiptRequest>  
    <positiveOnly/>  
    <negativeOnly/>  
    <sendTo>   
      http://www.northwindtraders.com/msmq/PRIVATE$/AdminQueue  
    </sendTo>  
  </commitmentReceiptRequest>  
  

• <positiveOnly/>

  (Optional subelement of <commitmentReceiptRequest>, read/write.) Indicates that a positive acknowledgment message should be sent when the message is retrieved from the destination queue(PROPID_M_ACKNOWLEDGE or MSMQMessage.Ack set to MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE). This subelement is always accompanied by a <negativeOnly/> subelement.

• <negativeOnly/>

  (Optional subelement of <commitmentReceiptRequest>, read/write.) Indicates that a negative acknowledgment message should be sent when the message is not retrieved from the destination queue before the date and time specified in the <TTrq> element of the <Msmq> entry, that is, before expiration of the message's time-to-be-received timer. (PROPID_M_ACKNOWLEDGE or MSMQMessage.Ack set to MQMSG_ACKNOWLEDGMENT_NACK_RECEIVE or to MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE when the <positiveOnly/> subelement is also included).

• <sendTo>

  (Required as a subelement of <deliveryReceiptRequest> and <commitmentReceiptRequest>, read/write.) Specifies the queue to which the receipt or acknowledgment message is sent (PROPID_M_ADMIN_QUEUE or MSMQMessage.AdminQueueInfo). Note that this element must contain an HTTP direct format name.

  Although the <services> entry is optional, if it is included, the recipient SRMP processor must understand and process this entry and all of its contents for the successful processing of an HTTP message. The encoding of the <services> element must always contain the attribute se:mustUnderstand="1" to ensure this. Note that the namespace prefix attached to this attribute (se) refers to the SOAP envelope namespace, which is declared in the <Envelope> element.

  The following example shows how these properties are included in an HTTP message as elements of the <services> header entry:

  <services se:mustUnderstand="1">  
    <durable/>  
    <deliveryReceiptRequest>  
      <sendTo>  
        http://www.northwindtraders.com/msmq/PRIVATE$/AdminQ  
      </sendTo>  
    </deliveryReceiptRequest>  
    <commitmentReceiptRequest>  
      <positiveOnly/>  
      <negativeOnly/>  
      <sendTo>  
        http://www.northwindtraders.com/msmq/PRIVATE$/AdminQ  
      </sendTo>  
    </commitmentReceiptRequest>  
  </services>  
  

Note that although the SRMP specification provides a way to specify different administration queues for delivery and commitment (retrieval) receipts in the same message, Message Queuing will always use the last one specified in the message.

Elements of the <Stream> Entry

SRMP stream elements are generated for each type of transactional message:

• <streamId>

  (Required, read-only.) Specifies the identifier of the transaction (message stream) in which the message is being sent (PROPID_M_XACTID or MSMQMessage.TransactionId).

• <current>

  (Required, read-only.) Specifies the sequence number of the message in the stream. The value of this element must be 1 for the message initiating a stream.

• <previous>

  (Optional, read-only.) Specifies the sequence number of a previous message in the stream. The current message can be delivered only if a message whose sequence number is equal to the previous sequence number is present in the destination queue. The previous sequence number can be any number smaller than the current sequence number. The first or initiating message in a stream always carries a previous sequence number equal to zero.

• <start>

  (Read-only.) Outer element that may contain <sendReceiptsTo> as a subelement. The <start> element must appear in the <Stream> entry in a message initiating a stream and must not appear in any other messages belonging to that stream. The address to which the receipts, or order acknowledgment messages, are sent is fixed in the first message of a stream and cannot be changed in a subsequent message.

• <sendReceiptsTo>

  (Optional subelement of <start>, read-only.) Specifies the logical address of the queue to which receipts, or order acknowledgment messages, are sent. Order acknowledgment messages must be sent directly or redirected using a mapping file to the order queue on the computer sending the stream.

The recipient SRMP processor must understand and process the <Stream> entry and all of its contents for the successful processing of an HTTP message. The encoding of the <Stream> entry must always contain the attribute se:mustUnderstand="1" to ensure this. Note that the namespace prefix attached to this attribute (se) refers to the SOAP envelope namespace, which is declared in the <Envelope> element.

The following example shows how these properties are included in a transactional HTTP message as elements of a <Stream> header entry:

<Stream se:mustUnderstand="1">  
  <streamId>  
    uri:bb270336-75e0-426f-9a73-e1ac49204e05\4257713020257435654  
  </streamId>  
  <current>1</current>  
  <previous>0</previous>  
  <start>  
    <sendReceiptsTo>  
      http://www.northwindtraders.com/msmq/PRIVATE$/StreamReceipts   
    </sendReceiptsTo>  
  </start>  
</Stream>  

Elements of the <streamReceipt> Entry

A <streamReceipt> header entry is created only in an order acknowledgment message (stream receipt) sent for a transactional message. The <streamReceipt> element must contain exactly one <streamId> subelement and exactly one <lastOrdinal> subelement:

• <streamId>

  (Required.) Specifies the sequence identifier of the message stream being sent to the destination queue.

• <lastOrdinal>

  (Required.) Specifies the sequence number of the last transactional message in the message stream that has reached the destination queue.

  The following lines provide a complete example of a <streamReceipt> entry:

  <streamReceipt>  
    <streamId>4164812</streamId>  
    <lastOrdinal>4</lastOrdinal>  
  </streamReceipt>  
  

Elements of the <deliveryReceipt> Entry

No Message Queuing message properties are mapped directly to the optional <deliveryReceipt> header entry. This entry is created only in an acknowledgment message sent in response to a request to indicate that the original message reached the destination queue. The <deliveryReceipt> element must contain exactly one <receivedAt> subelement and exactly one <id> subelement. The <id> subelement is identical to the <id> subelement in the WS-Routing <path> element of the original message:

• <receivedAt>

  (Required, read-only.) Specifies the time when the original message reached the destination queue.

  The following lines provide a complete example of a <deliveryReceipt> entry:

  <deliveryReceipt>  
    <receivedAt>20010829T161432</receivedAt>  
    <id>uuid:2288926@ac3fd49c-e7d5-4354-ba8d-3e13fc6f677c</id>  
  </deliveryReceipt>  
  

Elements of the <commitmentReceipt> Entry

No Message Queuing message properties are mapped directly to the optional <commitmentReceipt> header entry. This entry is created only in an acknowledgment message sent in response to a request to indicate whether the original message is received from the destination queue before the date and time specified in the <TTrq> element of its <Msmq> entry, that is, before its time-to-be-received timer expires. The <commitmentReceipt> element must contain exactly one <decidedAt> subelement, exactly one <decision> subelement, and exactly one <id> subelement. The <id> subelement is identical to the <id> subelement in the WS-Routing <path> element of the original message:

• <decidedAt>

  (Required, read-only.) Specifies the date and time when the original message was received or its time-to-be-received timer expired. The string included in this element specifies the date and time in the form yyyymmddTseconds.

• <decision>

  (Required, read-only.) Indicates whether the original message was (positive) or was not (negative) received from the destination queue before its time-to-be-received timer expired.

  The following lines provide a complete example of a <commitmentReceipt> entry:

  <commitmentReceipt>  
    <decidedAt>20010829T161432</decidedAt>  
    <decision>positive</decision>  
    <id>uuid:2288926@ac3fd49c-e7d5-4354-ba8d-3e13fc6f677c</id>  
  </commitmentReceipt>  
  

More Information