Data Handler is the structure that represents the attachments and it provides functions for sending and receiving attachments in axiom. It is attached to a text node in axiom tree.

You can create a data handler by providing the path of the attachment file and the MIME type. Then, it should be attached to an axiom text element.

 image_om_ele = axiom_element_create(env, mtom_om_node, "image", ns1, &image_om_node);
 data_handler = axiom_data_handler_create(env, "axis2.jpg", "image/jpeg");
 data_text    = axiom_text_create_with_data_handler(env, image_om_node, data_handler, &text_om_node);
        

Of course you can create the data handler without specifying the file name and MIME type and then later set them in. This is specially useful when you already have your attachment contents in memory.

 
 data_handler = axiom_data_handler_create(env, NULL, NULL);
 axiom_data_handler_set_binary_data(data_handler, env, buffer, buffer_len);
 axiom_data_handler_set_content_type(data_handler, env,"image/jpeg");
 axiom_text_create_with_data_handler(env, mtom_om_node, data_handler, &text_node);
    

You can set whether the attachment should be sent in optimized or non optimized format on the axiom text,  which contains the data handler. However, if you have enableMTOM option set to false, the attachment will be sent in base64 format, irrespective of this option.

 data_text = axiom_text_create_with_data_handler(env, image_om_node, data_handler, &data_om_node);
 axiom_text_set_optimize(data_text, env, AXIS2_TRUE);
       

When receiving attachments, you can either save the attachment to a file or you can obtain it as a buffer with the buffer length.

axiom_data_handler_set_file_name(data_handler, env, text_str);
axiom_data_handler_write_to(data_handler, env);

buffer = axiom_data_handler_get_input_stream(data_handler, env);
buffer_len = axiom_data_handler_get_input_stream_len(data_handler, env);
mime_type =  axiom_data_handler_get_content_type(data_handler, env);

In receiving attachments, knowing the exact location of the binary attachment allows you to easily obtain axiom text and the data handler. However, if the location is unknown, you will have to iterate through the axiom tree, looking for axiom text containing data handlers. 

There is an easier way to access the attachments received. axiom_soap_builder object contains a hash table with content id (cid ) as the key and data_handler as the value. Content id is the value of the href attribute except "cid:". This uniquely identifies attachments received within a SOAP message.

<xop:Include href="cid:1.fea3613d-9541-4749-a558-b984a55a92f6@apache.org" xmlns:xop="http://www.w3.org/2004/08/xop/include"/>

soap_builder = axiom_soap_envelope_get_soap_builder(soap_envelope, env);
mime_body_parts = axiom_soap_builder_get_mime_body_parts(soap_builder, env);

By iterating through the hash table, you are able to obtain all attachments received. This technique can be used in the event of receiving attachments in SwA format as well.

if(mime_body_parts) {
    axutil_hash_index_t *hi = NULL;
    axis2_char_t *cid = NULL;
    axiom_data_handler_t *data_handler = NULL;
    for (hi = axutil_hash_first(mime_body_parts, env);
    	hi; hi = axutil_hash_next(env, hi))    
    {                                                           
    	axutil_hash_this(hi, (const void **)&cid, NULL, (void**)&data_handler); 
        if(cid && data_handler) 
        {
        	char *mime_type = NULL;
                char *data = NULL;
                int data_len = 0;

                axiom_data_handler_read_from (data_handler, env, &data, &data_len);
                mime_type = axiom_data_handler_get_content_type(data_handler, env);
		/** Use the attachment content here */
         }
    }
}

You can send attachments using the SwA format by setting swa option in axiom text containing the data handler. Note the absence of xop:include element.

 data_text = axiom_text_create_with_data_handler(env, image_om_node, data_handler, &data_om_node);
 axiom_text_set_is_swa(data_text, env, AXIS2_TRUE);
       

--MIMEBoundary09b42e84-c3d9-4d9e-b80b-91f834edc878
content-transfer-encoding: binary
content-id: <0.d9b487fa-22a2-4d63-b8c2-9a91ee4b4dc2@apache.org>content-type: application/xop+xml;charset=UTF-8;type="text/xml";
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Header/>
      <soapenv:Body>
         <ns1:mtomSample xmlns:ns1="http://ws.apache.org/axis2/c/samples/mtom">
            <ns1:fileName>test.jpg</ns1:fileName>
            <ns1:image>1.9f4dc218-ca93-46f7-86b2-129500358e23@apache.org</ns1:image>
         </ns1:mtomSample>
      </soapenv:Body>
   </soapenv:Envelope>--MIMEBoundary09b42e84-c3d9-4d9e-b80b-91f834edc878content-transfer-encoding: binarycontent-id: 
   <1.9f4dc218-ca93-46f7-86b2-129500358e23@apache.org>content-type: image/jpeg
Binary content goes here

Now you know all necessary detials on how to use Axis2/C to send and receive attachments. 

Axis2/C manual [3]

 MTOM Specification [4]

 SwA Specification [5]

Author

Nandika Jayawardana is a senior software engineer at wso2. nandika at wso2.com