2.2.3.4 Attachment and RTF Integration

  • Article

To integrate Attachment objects into an RTF body, the list of Attachment objects to integrate MUST be retrieved from the attachments table, as specified in [MS-OXCMSG] section 3.1.4.17. The attachment list MUST only include those Attachment objects that have a PidTagAttachmentHidden property ([MS-OXCMSG] section 2.2.2.24) whose value is equal to FALSE (0x00) or non-existent, and a PidTagRenderingPosition property ([MS-OXCMSG] section 2.2.2.16) whose value is not equal to 0xFFFFFFFF.

When the RTF reader is parsing RTF and it encounters an \objattph control word, it SHOULD add a new instance to the position array. The position array stores the location in the data stream where the object belongs. This location can be represented as the number of characters from the beginning of the rendered content.

After the RTF reader has finished parsing the entire RTF content and populating the position array, sufficient information is available to complete the integration process. The number of values in the position array SHOULD be compared to the number of values in the attachments list (retrieved from the attachments table). If the number of values does not match, the RTF reader ignores the locations specified in the position array and uses the data provided in the attachment list. This can be accomplished by emptying the position array. Any extra attachments SHOULD be inserted at the end of the rendered RTF, or MAY<15> be inserted using the rendering position stored in the PidTagRenderingPosition property ([MS-OXCMSG] section 2.2.2.16) of the attachment.

The attachment list and the position array SHOULD be enumerated in lock step. For each instance, if a value exists in the position array, the location specified in the position array SHOULD be used as the insert location.

The next step is to prepare the attachment for insertion. The preparations necessary for insertion of an object will vary depending on the RTF reader. For more information, an implementer should consult the documentation associated with their RTF reader.

After it is prepared, the location specified for the Attachment object SHOULD be selected. If the location in the position array is greater than the number of rendered characters in the body, the insert<16> location is set to the end of the rendered RTF body. That location is then replaced with the prepared Attachment object.

At this point, the insertion is complete, and the RTF reader moves to the next attachment in sequential order, and to the next entry in the position array.

As specified earlier in this section, if there are not sufficient instances in the position array, any remaining attachments in the attachments list SHOULD be appended to the end of the RTF body, or MAY<17> be inserted using the rendering position stored in the PidTagRenderingPosition property of the attachment. If there are extra values in the position array, RTF readers SHOULD simply ignore rendering them, as specified in [MSFT-RTF].

For an example of attachment integration, see section 3.2.