Genivia Home Documentation
DIME attachment functions

updated Fri Oct 16 2020 by Robert van Engelen
 
DIME attachment functions

This module defines functions to set and get DIME attachments. More...

Classes

struct  xsd__base64Binary
 XSD base64Binary structure with attachment data. More...
 
struct  _xop__Include
 XOP include structure with attachment data. More...
 
struct  xsd__hexBinary
 XSD hexBinary structure with attachment data. More...
 
struct  soap_dime
 Stores a linked list of DIME attachments received. More...
 

Functions

int soap_set_dime (struct soap *soap)
 Enable DIME attachments. More...
 
void soap_clr_dime (struct soap *soap)
 Disable DIME attachments. More...
 
int soap_set_dime_attachment (struct soap *soap, const char *ptr, size_t size, const char *type, const char *id, unsigned short optype, const char *option)
 Add a DIME attachment to the SOAP/XML message. More...
 
char * soap_dime_option (struct soap *soap, unsigned short optype, const char *option)
 Creates a DIME option. More...
 

Detailed Description

This module defines functions to set and get DIME attachments.

For more information on the DIME protocol, see for example https://msdn.microsoft.com/en-us/library/aa480488.aspx

There are two ways to add DIME attachments to SOAP/XML messages for sending:

Both methods also support streaming DIME attachments to send using the soap::fdimereadopen, soap::fdimeread, and soap::fdimereadclose callbacks that fetch the data to send, where a user-defined handle should be specified for the ptr parameter of soap_set_dime_attachment or the xsd__base64Binary::__ptr member variable instead of a pointer to the actual data. This handle can be used by the callbacks to fetch the specific data to transmit.

Receiving DIME attachments attached to SOAP/XML messages is automatic. The DIME attachments are converted to binary data and stored in the xsd__base64Binary structures that reference the DIME attachments via the xsd__base64Binary::id string, meaning that the xsd__base64Binary::__ptr (points to the data) and xsd__base64Binary::__size (data length) are populated automatically with the DIME binary data. However, if the streaming DIME callbacks soap::fdimewriteopen, soap::fdimewrite, and soap::fdimewriteclose are defined then the attachments are streamed to these callbacks instead.

For example, to send and receive a SOAP/XML message with DIME attachments using a serializable xsd__base64Binary structure:

// example .h file for soapcpp2
//gsoap ns service name: example
//gsoap ns service namespace: urn:example
unsigned char *__ptr; // pointer to binary data
int __size; // size of the binary data
char *id; // NULL to generate an id or assign this member variable a unique UUID
char *type; // MIME type of the data
char *options; // DIME options
};
int ns__webmethod(struct xsd__base64Binary *data, struct xsd__base64Binary *result);
// example client implementation based on the above example .h file for soapcpp2
#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
struct xsd__base64Binary data, result;
data.__ptr = ...; // points to binary image data to send
data.__size = ...; // size of the image data to send
data.id = NULL; // this will be assigned by the engine
data.type = "image/jpg";
data.options = soap_dime_option(soap, 0, "Picture.png"); // DIME option 0 = "Picture.png" to store file name
if (soap_call_ns__webmethod(soap, endpoint, NULL, &data, &result))
soap_print_fault(soap, stderr);
else
... // success, use the result
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
}
// example service implementation based on the above example .h file for soapcpp2
#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
... // serve requests with soap_bind, soap_accept, soap_ssl_accept, and soap_serve
}
int ns__webmethod(struct soap *soap, struct xsd__base64Binary *data, struct xsd__base64Binary *result)
{
// echo back the structure (as a DIME attachment)
result->__ptr = data->__ptr;
result->__size = data->__size;
retult->id = data->id;
retult->type = data->type;
retult->options = data->options;
return SOAP_OK;
}

Besides receiving the attachments in xsd__base64Binary structures, on the receiving side you can also iterate over the DIME attachments received as follows:

#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
... // call soap_call_ns__webmethod etc.
{
int n = 0;
struct soap_multipart *attachment;
for (attachment = soap->dime.list; attachment; attachment = attachment->next)
{
++n;
printf("Part %d:\n", n);
printf("ptr =%p\n", attachment->ptr);
printf("size =%ul\n", attachment->size);
printf("id =%s\n", attachment->id ? attachment->id : "");
printf("type =%s\n", attachment->type ? attachment->type : "");
// DIME options are formatted according to the DIME protocol
if (attachment->options)
{
// extract length of first option
size_t len = ((unsigned char)attachment->options[2] << 8) | ((unsigned char)attachment->options[3]);
// allocate and copy the first option, which is assumed to be a name
char *name = (char*)soap_malloc(soap, len + 1);
strncpy(name, attachment->options + 4, len);
name[len] = '\0';
printf("option=%s\n", name);
}
}
}
}

In C++ you can use an iterator for the last part of this example:

struct soap *soap = soap_new();
... // call soap_call_ns__webmethod etc.
int n = 0;
for (soap_multipart::iterator i = soap->dime.begin(); i != soap->dime.end(); ++i)
{
++n;
printf("Part %d:\n", n);
printf("ptr =%p\n", i->ptr);
... // etc
}

At the server side the code to retrieve the DIME attachments is the same.

Function Documentation

void soap_clr_dime ( struct soap soap)

Disable DIME attachments.

This function disables DIME attachments, unless the data to serialize as an XML message contains attachments defined by xsd__base64Binary and _xop__Include structures.

char* soap_dime_option ( struct soap soap,
unsigned short  optype,
const char *  option 
)

Creates a DIME option.

This function creates a DIME option-formatted string for the xsd__base64Binary::options member variable or _xop__Include::options member variable.

Returns
a DIME option-formatted string
Parameters
soapsoap context
optypea 16 bit DIME option type
optionone DIME option as a text string
int soap_set_dime ( struct soap soap)

Enable DIME attachments.

This function enables sending DIME attachments. This function is generally not required because DIME attachments are automatically detected as xsd__base64Binary and _xop__Include structures in the data to serialize as an XML message with the attachments automatically added or DIME attachments can be explicitly added with soap_set_dime_attachment.

int soap_set_dime_attachment ( struct soap soap,
const char *  ptr,
size_t  size,
const char *  type,
const char *  id,
unsigned short  optype,
const char *  option 
)

Add a DIME attachment to the SOAP/XML message.

This function adds a DIME attachment to the XML message to send. The specified ptr points to the data to send of length specified by size. The type parameter indicates the MIME type of the data or can be NULL. The id parameter uniquely identifies the attachment in the message, which can be omitted by specifying NULL. The option parameter is an option such as a description of the data and optype is a user-defined option type (as per DIME option specification format). The ptr parameter must be persistent. The ptr parameter passed to this function must be persistent in memory until the attachment was sent. Returns SOAP_OK or a soap_status error code.

When streaming DIME attachments are enabled by defining the soap::fdimereadopen, soap::fdimeread, soap::fdimereadclose then the ptr parameter should point to a user-defined structure that is passed to soap::fdimereadopen as the handle parameter.

Example:
#include "soapH.h"
struct soap *soap = soap_new1(SOAP_IO_CHUNK);
const char *data = ...; // points to data to send
size_t size = ...; // length of the data
soap->connect_timeout = 30; // 30 seconds max connect stall time
soap->send_timeout = soap_recv_timeout = 5; // 5 seconds max socket stall time (unlimited by default)
soap->transfer_timeout = 30; // 30 seconds max message transfer time (unlimited by default)
soap->recv_maxlength = 1048576; // limit messages received to 1MB (2GB by default)
soap_set_dime_attachment(soap, data, size, "image/jpg", NULL, 0, "Picture");
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
{
soap_print_fault(soap, stderr);
if (soap->errnum == 0) // timed out, exit program
exit(EXIT_FAILURE);
}
else
{
... // success
}
soap_end(soap);
soap_free(soap);
See also
xsd__base64Binary, _xop__Include, soap_rand_uuid, soap::fdimereadopen, soap::fdimeread, soap::fdimereadclose.
Returns
SOAP_OK or a soap_status error code
Parameters
soapsoap context
ptrpointer to data
sizelength of the data
typeMIME type of the data or NULL
idcontent ID of the data or NULL
optypea 16 bit DIME option type
optionone DIME option as a text string or NULL