Genivia Home Documentation
DIME attachment functions

updated Mon Apr 25 2022 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))
else
... // success, use the result
}
// 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

◆ 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
optypea 16 bit DIME option type
optionone 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"
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, ...))
{
if (soap->errnum == 0) // timed out, exit program
exit(EXIT_FAILURE);
}
else
{
... // success
}
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
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
xsd__base64Binary::__size
int __size
size of the binary data
Definition: stdsoap2.h:9694
xsd__base64Binary::id
char * id
extra member: NULL to generate an id or assign this member variable a unique UUID
Definition: stdsoap2.h:9695
soap_multipart::size
size_t size
size of data content
Definition: stdsoap2.h:10286
soap_multipart::id
const char * id
DIME/MIME/MTOM content ID or form data name.
Definition: stdsoap2.h:10287
soap_dime::end
soap_multipart::iterator end()
C++ only: an iterator over soap_multipart attachments.
soap_multipart
DIME/MIME/MTOM attachment data received by the engine.
Definition: stdsoap2.h:10283
soap_new
struct soap * soap_new()
Allocate and initialize a new soap context.
soap_dime::list
struct soap_multipart * list
list of DIME attachments received
Definition: stdsoap2.h:9826
soap::dime
struct soap_dime dime
DIME attachments received.
Definition: stdsoap2.h:4175
soap_free
void soap_free(struct soap *soap)
Finalize and free the given soap context from unmanaged heap memory.
SOAP_OK
#define SOAP_OK
The soap_status code for no error (zero)
Definition: stdsoap2.h:2260
soap_destroy
void soap_destroy(struct soap *soap)
Delete all dynamically-allocated C++ objects managed by the specified soap context.
soap_dime_option
char * soap_dime_option(struct soap *soap, unsigned short optype, const char *option)
Creates a DIME option.
soap::endpoint
char endpoint[SOAP_TAGLEN]
The endpoint string as received on the server side.
Definition: stdsoap2.h:4009
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:3133
soap_dime::begin
soap_multipart::iterator begin()
C++ only: an iterator over soap_multipart attachments.
soap_malloc
void * soap_malloc(struct soap *soap, size_t len)
Allocate a block of heap memory managed by the specified soap context.
soap::errnum
int errnum
The errno value of the last failed IO operation.
Definition: stdsoap2.h:2918
soap_end
void soap_end(struct soap *soap)
Delete all data from heap memory managed by the specified soap context and release the freed memory b...
soap_new1
struct soap * soap_new1(soap_mode input_and_output_mode)
Allocate and initialize a new soap context with input and output soap_mode flags.
soap
Context with the engine state.
Definition: stdsoap2.h:2795
soap::transfer_timeout
int transfer_timeout
User-definable timeout to send or receive an entire message, positive timeout values are seconds,...
Definition: stdsoap2.h:3147
soap_print_fault
void soap_print_fault(struct soap *soap, FILE *fd)
Print error message on the specified output.
soap_multipart::iterator
soap_multipart_iterator iterator
C++ only: an iterator over soap_multipart attachments.
Definition: stdsoap2.h:10294
soap::send_timeout
int send_timeout
User-definable timeout to send a packet of data, positive timeout values are seconds,...
Definition: stdsoap2.h:3175
xsd__base64Binary::type
char * type
extra member: MIME type of the data
Definition: stdsoap2.h:9696
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:3250
soap_multipart::options
const char * options
DIME options.
Definition: stdsoap2.h:10289
soap_multipart::type
const char * type
DIME/MIME/MTOM type (MIME type format)
Definition: stdsoap2.h:10288
xsd__base64Binary::__ptr
unsigned char * __ptr
pointer to binary data
Definition: stdsoap2.h:9693
soap_multipart::ptr
const char * ptr
points to raw data content
Definition: stdsoap2.h:10285
xsd__base64Binary
XSD base64Binary structure with attachment data.
Definition: stdsoap2.h:9692
xsd__base64Binary::options
char * options
extra member: DIME options or a description of the MIME attachment or NULL
Definition: stdsoap2.h:9697
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_multipart::next
struct soap_multipart * next
next attachment in the linked list
Definition: stdsoap2.h:10284
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:1580