|  | Home | Documentation | DIME attachment functions updated by Robert van Engelen |

DIME attachment functions

This module describes 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.
void | soap_clr_dime (struct soap *soap)
| Disable DIME attachments.
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.
char * | soap_dime_option (struct soap *soap, unsigned short optype, const char *option)
| Creates a DIME option.

## Detailed Description

This module describes 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:

- use soap_set_dime_attachment to explicitly add an attachment that contains the specified source of data;
- use xsd__base64Binary or _xop__Include structures in the serializable data of a SOAP/XML message, where the specified data is serialized in DIME attachments automatically when one of the id, type or options member variables are non-NULL.

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
struct xsd__base64Binary {
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);
xsd__base64Binary
XSD base64Binary structure with attachment data.
Definition stdsoap2.h:10045
xsd__base64Binary::options
char * options
extra member: DIME options or a description of the MIME attachment or NULL
Definition stdsoap2.h:10050
xsd__base64Binary::id
char * id
extra member: NULL to generate an id or assign this member variable a unique UUID
Definition stdsoap2.h:10048
xsd__base64Binary::__ptr
unsigned char * __ptr
pointer to binary data
Definition stdsoap2.h:10046
xsd__base64Binary::__size
int __size
size of the binary data
Definition stdsoap2.h:10047
xsd__base64Binary::type
char * type
extra member: MIME type of the data
Definition stdsoap2.h:10049
// 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);
}
soap_free
*Finalize and free the given ::soap context from unmanaged heap memory void soap_free(struct soap *soap)
soap_end
*Delete all data from heap memory managed by the specified ::soap context and release the freed memory back to the heap int soap_end(struct soap *soap) * @returns `
soap_dime_option
char * soap_dime_option(struct soap *soap, unsigned short optype, const char *option)
Creates a DIME option.
soap_print_fault
void soap_print_fault(struct soap *soap, FILE *fd)
Print error message on the specified output.
soap
Context with the engine state.
Definition stdsoap2.h:2929
// 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;
}
SOAP_OK
#define SOAP_OK
The soap_status code for no error (zero).
Definition stdsoap2.h:2392

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);
}
}
}
}
soap_malloc
*Allocate a block of heap memory managed by the specified ::soap context void * soap_malloc(struct soap *soap, size_t len) * @returns pointer to the allocated block of memory or NULL on failure to allocate(out of memory)
soap_dime::list
struct soap_multipart * list
list of DIME attachments received
Definition stdsoap2.h:10179
soap_multipart
DIME/MIME/MTOM attachment data received by the engine.
Definition stdsoap2.h:10638
soap_multipart::type
const char * type
DIME/MIME/MTOM type (MIME type format).
Definition stdsoap2.h:10643
soap_multipart::next
struct soap_multipart * next
next attachment in the linked list
Definition stdsoap2.h:10639
soap_multipart::options
const char * options
DIME options.
Definition stdsoap2.h:10644
soap_multipart::ptr
const char * ptr
points to raw data content
Definition stdsoap2.h:10640
soap_multipart::id
const char * id
DIME/MIME/MTOM content ID or form data name.
Definition stdsoap2.h:10642
soap_multipart::size
size_t size
size of data content
Definition stdsoap2.h:10641
soap::dime
*DIME attachments received struct soap_dime dime
Definition stdsoap2.h:4309

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
}
soap_dime::begin
soap_multipart::iterator begin()
C++ only: an iterator over soap_multipart attachments.
soap_dime::end
soap_multipart::iterator end()
C++ only: an iterator over soap_multipart attachments.
soap_multipart::iterator
soap_multipart_iterator iterator
C++ only: an iterator over soap_multipart attachments.
Definition stdsoap2.h:10649

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

## Function Documentation

## ◆ soap_clr_dime()

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.

## ◆ soap_dime_option()

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

  soap | soap context
  optype | a 16 bit DIME option type
  option | one DIME option as a text string

## ◆ soap_set_dime()

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.

## ◆ 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_destroy(soap);
soap_end(soap);
soap_free(soap);
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.
SOAP_IO_CHUNK
#define SOAP_IO_CHUNK
soap_mode IO output flag value to send HTTP chunked messages, buffers the message in packets of size ...
Definition stdsoap2.h:1672
soap::errnum
int errnum
The errno value of the last failed IO operation.
Definition stdsoap2.h:3052
soap::recv_maxlength
ULONG64 recv_maxlength
User-definable maximum message length that is permitted to be received, zero means unlimited (the val...
Definition stdsoap2.h:3267
soap::send_timeout
int send_timeout
User-definable timeout to send a packet of data, positive timeout values are seconds,...
Definition stdsoap2.h:3309
soap::endpoint
char endpoint[SOAP_TAGLEN]
The endpoint URL as received on the server side.
Definition stdsoap2.h:4143
soap::connect_timeout
int connect_timeout
User-definable timeout when waiting to connect to a server at the client-side, positive timeout value...
Definition stdsoap2.h:3384
soap::transfer_timeout
int transfer_timeout
User-definable timeout to send or receive an entire message, positive timeout values are seconds,...
Definition stdsoap2.h:3281

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

  soap | soap context
  ptr | pointer to data
  size | length of the data
  type | MIME type of the data or NULL
  id | content ID of the data or NULL
  optype | a 16 bit DIME option type
  option | one DIME option as a text string or NULL