Standards for Technology in Automotive Retail
| Standards for Technology in Automotive Retail | |
The attachment element is an optional element that may appear in the SOAP BODY payload's content section. Implementations may NOT place this attachment elsewhere in the SOAP BODY. The use of the element is to enable the transportation of non-xml formatted data, without the need to encode it into an XML compatible format.
Below is an example of a ProcessMessage request carrying a binary image using the attachment element:
Example 10.1. Sample Message with Attachment
<attachment xmlns="http://www.starstandards.org/webservices/2009/transport"> <id>token</id> (optional) <fileName>fileName</fileName> (optional) <attachmentData>#@#$@$@@FADA#$ADFAAFSERWADFVadadfarW</attachmentData> (optional) <mimeCode>mimeCode</mimeCode> (required) <uriReference>http://tempuri.org</uriReference> (optional) </attachment>
The STAR Web Services 4.0 template WSDL provided by STAR
includes the necessary definition. The attachment element itself may occur
many times, and is optional.
id - a unique identifier for this attachment. For WS-Attachments implementations this can be the Multipart-Mime Content identifier.
filename - the name of the file to be created.
attachmentData - binary encoded or MTOM/XOP information. MTOM frameworks may replace this with a XOP element that refers to the appropriate Muiltipart-Mime Content identifier.
mimeCode - a mime code that describes the type of content being attached. i.e. application/text, application/xml, image/png, image/jpg
uriReference - a URL where the attachment can be retrieved if it is stored on a server.
The STAR WSDL includes the necessary information to enable frameworks to understand and create the necessary code for MTOM based attachments. This is accomplished by specifying at the XML Schema level the use of the xmime:expectedContentTypes="application/octet-stream".
Example 10.2. WSDL MTOM Encoding
<xsd:element name="attachmentData" type="xsd:base64Binary" xmime:expectedContentTypes="application/octet-stream">
<xsd:annotation>
<xsd:documentation source="http://www.starstandard.org">Binary data using base64Binary encoding.</xsd:documentation>
</xsd:annotation>
</xsd:element>Use of the content type application/octet-stream allows for the transmittal of any type of binary data. Further information on the specific content type can be specified using the appropriate mimeCode element for the attachment component. A framework that supports MTOM will use the xmime:epectedContentType during code generation from the WSDL to create the appropriate processing instructions. The following example of an MTOM/XOP encoded message comes from the XOP 1.0 specification. [XOP]
Example 10.3. MTOM encoded attachment
MIME-Version: 1.0
Content-Type: Multipart/Related;boundary=MIME_boundary;
type="application/xop+xml";
start="<mymessage.xml@example.org>";
startinfo="application/soap+xml; action=\"ProcessData\""
Content-Description: A SOAP message with my pic and sig in it
--MIME_boundary
Content-Type: application/xop+xml;
charset=UTF-8;
type="application/soap+xml; action="ProcessData\""
Content-Transfer-Encoding: 8bit
Content-ID: <mymessage.xml@example.org>
<soap:Envelope
xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
xmlns:xmlmime='http://www.w3.org/2004/11/xmlmime'>
<soap:Body>
<m:data xmlns:m='http://example.org/stuff'>
<m:photo xmlmime:contentType='image/png'>
<xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include'
href='cid:http://example.org/me.png'/>
</m:photo>
<m:sig xmlmime:contentType='application/pkcs7-signature'>
<xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include'
href='cid:http://example.org/my.hsh'/>
</m:sig>
</m:data>
</soap:Body>
</soap:Envelope>
--MIME_boundary
Content-Type: image/png
Content-Transfer-Encoding: binary
Content-ID: <http://example.org/me.png>
// binary octets for png
--MIME_boundary
Content-Type: application/pkcs7-signature
Content-Transfer-Encoding: binary
Content-ID: <http://example.org/my.hsh>
// binary octets for signature
--MIME_boundary--A STAR attachments element that was processed by MTOM with a XOP include would look Example 10.4, “STAR MTOM encoded Attachment Element”.
Example 10.4. STAR MTOM encoded Attachment Element
<attachment xmlns="http://www.starstandards.org/webservices/2009/transport">
<filename>MyAttachment.png</filename>
<attachmentData>
<xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include'
href='cid:http://example.org/MyAttachment.png'/>
</attachmentData>
<mimeCode>image/png</mimeCode>
</attachment> The xop:Include href would refer to the Content-ID where the attached data can be retrieved from the Multipart-Mime boundary. The generation of the XOP include is handled by the MTOM framework, and is encoded before the message is sent over the wire by the framework. It is decoded on the receiving end. To the programmer it looks as if it was normal XML encoded data that was sent and received.