![]() |
Home | Documentation |
MIME attachment functions
updated Sat Sep 23 2023 by Robert van Engelen
|
This module defines functions to set and get MIME/MTOM attachments. More...
Classes | |
| struct | soap_mime |
| Stores a linked list of MIME attachments received. More... | |
| struct | soap_multipart |
| DIME/MIME/MTOM attachment data received by the engine. More... | |
Enumerations | |
| enum | soap_mime_encoding { SOAP_MIME_NONE, SOAP_MIME_7BIT, SOAP_MIME_8BIT, SOAP_MIME_BINARY, SOAP_MIME_QUOTED_PRINTABLE, SOAP_MIME_BASE64, SOAP_MIME_IETF_TOKEN, SOAP_MIME_X_TOKEN } |
| RFC2045 MIME content transfer encodings. More... | |
Functions | |
| int | soap_set_mime_attachment (struct soap *soap, const char *ptr, size_t size, enum soap_mime_encoding encoding, const char *type, const char *id, const char *location, const char *description) |
| Add a MIME attachment to the SOAP/XML message. More... | |
| int | soap_set_mime (struct soap *soap, const char *boundary, const char *start) |
| Enable MIME attachments. More... | |
| void | soap_clr_mime (struct soap *soap) |
| Disable MIME attachments. More... | |
| int | soap_post_check_mime_attachments (struct soap *soap) |
| Enable post-processing of MIME/MTOM attachments. More... | |
| int | soap_check_mime_attachments (struct soap *soap) |
| Check for a MIME/MTOM attachment. More... | |
| struct soap_multipart * | soap_recv_mime_attachment (struct soap *soap, void *handle) |
| Get a MIME/MTOM attachment. More... | |
This module defines functions to set and get MIME/MTOM attachments.
To enable MIME or MTOM, first initialize the soap context with SOAP_ENC_MIME (for MIME) or SOAP_ENC_MTOM (for MTOM) using soap_new1, soap_init1, soap_set_mode, or soap_set_mime to enable MIME and also to set a start id. To disable MIME use soap_clr_mime.
There are two ways to add MIME/MTOM attachments to SOAP/XML messages for sending:
soap_set_mime_attachment to explicitly add an attachment that contains the specified source of data;xsd__base64Binary (MIME and MTOM) or _xop__Include (MTOM) structures in the serializable data of a SOAP/XML message, where the specified data is serialized in MIME/MTOM attachments automatically when one of the id, type or options member variables are non-NULL.Both methods also support streaming MIME attachments to send using the soap::fmimereadopen, soap::fmimeread, and soap::fmimereadclose callbacks that fetch the data to send, where a user-defined handle should be specified for the ptr parameter of soap_set_mime_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 MIME/MTOM attachments attached to SOAP/XML messages is automatic. The MIME/MTOM attachments are converted to binary data and stored in the xsd__base64Binary structures that reference the MIME/MTOM 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 MIME/MTOM binary data. However, if the streaming MIME callbacks soap::fmimewriteopen, soap::fmimewrite, and soap::fmimewriteclose are defined then the attachments are streamed to these callbacks instead.
For example, to send and receive a SOAP/XML message with MIME attachments using a serializable xsd__base64Binary structure:
To send MIME attachments without SOAP/XML (i.e. with REST methods), simply add attachments with soap_set_mime_attachment. The soap_end_send function then adds the attachments before finalizing the message transmission. To receive MIME attachments without SOAP/XML (i.e. with REST methods), simply call soap_begin_recv (not needed at the server side since this is already called to parse the HTTP header) and soap_end_recv.
For example a client-side multipart-related POST operation that sends a multipart-related message with one MIME attachment and receives a message consisting of multipart-related MIME attachments:
In C++ you can use an iterator for the last part of this example:
At the server side the code to retrieve the REST message sent consisting of a set of multipart-related MIME attachments is the same. To respond with multipart-related MIME attachments use soap_set_mime and use soap_set_mime_attachment to add attachments. For example:
To disable MIME again, use soap_clr_mime.
| enum soap_mime_encoding |
RFC2045 MIME content transfer encodings.
These values are used by the soap_set_mime_attachment function parameter encoding.
SOAP_MIME_NONE to transmit any data of any type which is usually the purpose of MIME/MTOM attachments to SOAP/XML.soap_set_mime_attachment. | int soap_check_mime_attachments | ( | struct soap * | soap | ) |
Check for a MIME/MTOM attachment.
This function checks the presence of a MIME/MTOM attachment after calling a service operation by returning nonzero when attachments are present. Returns nonzero if attachments are present. Requires soap_post_check_mime_attachments.
soap_post_check_mime_attachments.| soap | soap context |
| void soap_clr_mime | ( | struct soap * | soap | ) |
Disable MIME attachments.
This function disables MIME attachments such as after sending a multipart-related message with attachments to switch back to non-multipart-related messaging, unless the data to serialize as a message contains attachments such as xsd__base64Binary for MIME attachments and _xop__Include for MTOM attachments.
| soap | soap context |
| int soap_post_check_mime_attachments | ( | struct soap * | soap | ) |
Enable post-processing of MIME/MTOM attachments.
This function enables post-processing of MTOM/MIME attachments attached to a message and is useful when MIME/MTOM are streamed (asynchronously) by configuring the callbacks ::fmimewriteopen, soap::fmimewrite, and soap::fmimewriteclose to write the attachment to memory, file or, other resources. By calling this function, the presence of MIME/MTOM attachments must be explicitly checked after each message is received by calling soap_check_mime_attachments. When this function returns nonzero (true), soap_recv_mime_attachment must be called repeatedly to retrieve each attachment until this function returns NULL indicating the end of attachments and the channel is closed, or if an error occurred with soap::error set to a nonzero soap_status error code.
If attachments are not referenced by the SOAP/XML message received, then normallly an error will be produced to indicate that attachments exist that were not converted into binary xsd__base64Binary or _xop__Include structures (i.e. deserialized from the message by resolving references to MIME/MTOM attachments). This error can be avoided by using soap_post_check_mime_attachments to indicate that attachments may appear that cannot be automatically resolved and should be handled explicitly by calling soap_check_mime_attachments and soap_recv_mime_attachment.
soap_post_check_mime_attachments is used, every message received must be followed by a call to soap_check_mime_attachments. When this function returns nonzero, soap_check_mime_attachments must be called repeatedly until this function returns NULL. This sequence of calls is necessary to properly handle messages with and without attachments. The connection is closed if HTTP keep-alive is not enabled. With HTTP keep-alive enabled, this sequence of calls allows the next message to be properly received.soap_check_mime_attachments, soap_recv_mime_attachment, soap::fmimewriteopen, soap::fmimewrite, soap::fmimewriteclose.SOAP_OK or a soap_status error code | soap | soap context |
| struct soap_multipart* soap_recv_mime_attachment | ( | struct soap * | soap, |
| void * | handle | ||
| ) |
Get a MIME/MTOM attachment.
This function parses an attachment and invokes the MIME callbacks when set. The handle parameter is passed to fmimewriteopen. The handle may contain any data that is extracted from the SOAP message body to guide the redirection of the stream in the callbacks. Returns a struct with a char *ptr member that contains the handle value returned by the fmimewriteopen callback, and char *id, char *type, and char *description member variables with the MIME id, type, and description info when present in the attachment.
| soap | soap context |
| handle | a handle to pass to the callbacks |
| int soap_set_mime | ( | struct soap * | soap, |
| const char * | boundary, | ||
| const char * | start | ||
| ) |
Enable MIME attachments.
This function enables sending MIME attachments. This function is generally not required when the context is initialized with SOAP_ENC_MIME, because MIME 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 MIME attachments can be explicitly added with soap_set_mime_attachment. Parameter boundary specifies a MIME boundary string or NULL to have the engine generate a MIME boundary string. Parameter start specifiesthe start content ID for the first MIME body containing the SOAP or XML message. When NULL, the start ID of the SOAP message is <SOAP-ENV:Envelope>.
| soap | soap context |
| boundary | MIME boundary string to use or NULL to generate a random boundary |
| start | string id of the first MIME attachment with the SOAP/XML message or NULL |
| int soap_set_mime_attachment | ( | struct soap * | soap, |
| const char * | ptr, | ||
| size_t | size, | ||
| enum soap_mime_encoding | encoding, | ||
| const char * | type, | ||
| const char * | id, | ||
| const char * | location, | ||
| const char * | description | ||
| ) |
Add a MIME attachment to the SOAP/XML message.
This function adds a MIME attachment to a SOAP/XML message to send. The specified ptr points to the data to send of length specified by size. The encoding parameter is a soap_mime_encoding value that is recommended to be specified as SOAP_MIME_NONE to specify that the MIME data content is not encoded in any way (the MIME attachment function simply copies the raw data to the MIME block without encoding). The type parameter is required and indicates the MIME type of the data, such as "image/jpg". The id parameter uniquely identifies the attachment in the message, which can be omitted by specifying NULL. The location parameter specifies a location string or NULL. The description parameter is a string that describes the data or NULL. Returns SOAP_OK or a soap_status error code.
There are two ways to add MIME/MTOM attachments to SOAP/XML:
soap_set_mime_attachment to explicitly add an attachment that contains the specified source of data;xsd__base64Binary or _xop__Include structures in the serializable data of a SOAP/XML message, where the specified data is serialized in MIME/MTOM attachments automatically when one of the id, type or options member variables are non-NULL. This option requires SOAP_ENC_MIME or SOAP_ENC_MTOM.Both methods support streaming MIME/MTOM attachments, where a user-defined handle instead of the actual data is specified for the ptr parameter or the __ptr member variable.
xsd__base64Binary, _xop__Include, soap_rand_uuid, soap::fmimereadopen, soap::fmimeread, soap::fmimereadclose.SOAP_OK or a soap_status error code | soap | soap context |
| ptr | pointer to data |
| size | length of the data |
| encoding | encoding of the data |
| type | MIME type of the data |
| id | content ID of the data or NULL |
| location | location of the data or NULL |
| description | description of the data or NULL |