![]() |
Home | Documentation |
DIME attachment functions
updated Fri Jan 17 2025 by Robert van Engelen
|
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. | |
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. |
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:
Besides receiving the attachments in xsd__base64Binary structures, on the receiving side you can also iterate over the DIME attachments received as follows:
In C++ you can use an iterator for the last part of this example:
At the server side the code to retrieve the DIME attachments is the same.
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.
soap | soap context |
optype | a 16 bit DIME option type |
option | one 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.
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 |