GSOAP MTOM, gsoapmtom

GSOAP MTOM, gsoapmtom
Preface

Knowledge to be prepared: wsdl, soap, gSOAP, C ++, and fidder.

Section 1 instructions for use

MTOM (Message Transmission Optimization mechanic) is a new (relative MIME, DIME) SOAP Message Transmission attachment format. The MTOM attachment is essentially a standard MIME attachment referenced in the SOAP body tag. You can use a DIME attachment instead of a MIME attachment.

MTOM is implemented in SOAP 1.2 and uses the XOP namespace. XOP Include element xop: include (in the SOAP body Tag) is used to reference attachments (multiple attachments can be referenced ).

Since the MTOM method is used to forcibly specify that attachments need to be referenced in the SOAP message body, GSoap serializes and deserializes binary attachments of MTOM and MIME in a way similar to DIME. The binary structure is prefixed inImport/xop. hFile definition:

 
//gsoap xop schema import: http://www.w3.org/2004/08/xop/include
struct _xop__Include
{
unsigned char *__ptr;
int __size;
char *id;
char *type;
char *options;
};
typedef struct _xop__Include _xop__Include;

BesidesId, typeThere are also two options: _ ptr and _ size. The process of sending and receiving mtopm xop attachments is completely automatic.IdAssociate the attachment (the typical content is CID or UUID ). WhenIdIf it is NULL or NULL, Gsoap will allocate a unique CID.TypeField specifies the MIME type of the binary data, and optional options can be used to transmit additional instructions for attachments. The field declaration sequence of the struct is sensitive (that is, the variable declaration sequence of the struct cannot be changed ).

 

You can declare that your data struct contains the attachment definition of xop. h MTOM, for example:

 
#import ïmport/soap12.h"
/* alternatively, without the import above, use:
//gsoap SOAP-ENV schema namespace: http://www.w3.org/2003/05/soap-envelope
//gsoap SOAP-ENC schema namespace: http://www.w3.org/2003/05/soap-encoding
*/
#import ïmport/xop.h"
#import ïmport/xmime5.h"
//gsoap x schema namespace: http://my.first.mtom.net
struct x__myData
{
   _xop__Include xop__Include; // attachment
   @char *xmime5__contentType; // and its contentType
};
int x__myMTOMtest(struct x__myData *in, struct x__myData *out);

As shown above, in the header file definition of gSOAP for MTOM and DIME attachments, there is no difference except that the SOAP 1.2 and xop _ Include elements are required for MTOM attachments.

When the x_myData instance is serialized,IdAndTypeFields cannot be NULL, And the soap structure content of gSOAP is identifiedWhen SOAP_ENC_MTOM is used, the attachment is transmitted as the mtom mime attachment.

 
struct soap *soap = soap_new1(SOAP_ENC_MTOM);

If this identifier is not set, it will be transmitted as DIME.

If your current client and service are based on non-stream DIME attachments using the SOAP body reference mechanism (therefore, the soap_set_dime_attachment function is not used) or pure base64 binary XML data elements, it is easy to use MTOM to rename xop _ Include and use the binary SOAP_ENC_MTOM identification and SOAP 1.2 namespace.

 

Section 2 stream receiving MTOM/MIME

The stream receiving MTOM/MIME function uses a callback function to capture and store data during attachment transmission. Three callback functions are used to receive MTOM/MIME output (write) in a streaming manner, and three callback functions are used to receive MTOM/MIME input (read) in a streaming manner ).

The following are the three callback functions of the input (read) Attachment:

 
void *(*soap.fmimereadopen)(struct soap *soap, void *handle,const char *id, const char *type, const char *description)  
  
size_t (*soap.fmimeread)(struct soap *soap, void *handle, char *buf, size_t len)  
  
void(*soap.fmimereadclose)(struct soap *soap, void *handle)

The following are the three callback functions appended to the output (write:

 
void *(*soap.fmimewriteopen)(struct soap *soap, void *handle,const char *id, const char *type, const char *description,enum soap_mime_encoding encoding)  
  
int (*soap.fmimewrite)(struct soap *soap, void *handle,const char *buf, size_t len)  
  
void(*soap.fmimewriteclose)(struct soap *soap, void *handle)

In addition, a void * user field structure soap data structure can pass user-defined data to the callback function. In this way, you can set soap. The user needs to direct the callback to the application data, such as a file name.

The following example shows that the client initializes An Image Attachment structure and the stream file is a MTOM attachment without HTTP blocks:

 
int main()
{
struct soap soap;
struct xsd__base64Binary image;
   FILE *fd;
struct stat sb;
   soap_init1(&soap, SOAP_ENC_MTOM); // mandatory to enable MTOM
if (!fstat(fileno(fd), &sb) && sb.st_size > 0)
   { // because we can get the length of the file, we can stream it without chunking
      soap.fmimereadopen = mime_read_open;
      soap.fmimereadclose = mime_read_close;
      soap.fmimeread = mime_read;
      image.__ptr = (unsigned char*)fd; // must set to non-NULL (this is our fd handle which we need in the callbacks)
      image.__size = sb.st_size; // must set size
   }
else
   { // don't know the size, so buffer it
      size_t i;
int c;
      image.__ptr = (unsigned char*)soap_malloc(&soap, MAX_FILE_SIZE);
for (i = 0; i < MAX_FILE_SIZE; i++)
      {
if ((c = fgetc(fd)) == EOF)
break;
         image.__ptr[i] = c;
      }
      fclose(fd);
      image.__size = i;
   }
   image.type = "image/jpeg"; // MIME type
   image.options = "This is my picture"; // description of object
   soap_call_ns__method(&soap, ...);
   ...
}
void *mime_read_open(struct soap *soap, void *handle, const char *id, const char *type, const char *description)
{ return handle;
}
void mime_read_close(struct soap *soap, void *handle)
{ fclose((FILE*)handle);
}
size_t mime_read(struct soap *soap, void *handle, char *buf, size_t len)
{ return fread(buf, 1, len, (FILE*)handle);
}

 

The following example shows that the MTOM/MIME stream is stored in a file by a client:

 
int main()
{ struct soap soap;
   soap_init(&soap);
   soap.fmimewriteopen = mime_write_open;
   soap.fmimewriteclose = mime_write_close;
   soap.fmimewrite = mime_write;
   soap_call_ns__method(&soap, ...);
   ...
}
void *mime_write_open(struct soap *soap, const char *id, const char *type, const char *description, enum soap_mime_encoding encoding)
{
   FILE *handle = fopen("somefile", "wb");
   // We ignore the MIME content transfer encoding here, but should check
if (!handle)
   {
      soap->error = SOAP_EOF;
      soap->errnum = errno; // get reason
   }
return (void*)handle;
}
void mime_write_close(struct soap *soap, void *handle)
{ fclose((FILE*)handle);
}
int mime_write(struct soap *soap, void *handle, const char *buf, size_t len)
{
   size_t nwritten;
while (len)
   {
      nwritten = fwrite(buf, 1, len, (FILE*)handle);
if (!nwritten)
      {
         soap->errnum = errno; // get reason
return SOAP_EOF;
      }
      len -= nwritten;
      buf += nwritten;
   }
return SOAP_OK;
}

 

File Management on the server is also dependent on the implementation of callback functions. The following is the code written by the mtom-stream server in the example program provided by gSOAP.

 
void *mime_server_write_open(struct soap *soap, void *unused_handle, const char *id, const char *type, const char *description, enum soap_mime_encoding encoding) 
{ 
    /* Note: the 'unused_handle' is always NULL */
    /* Return NULL without setting soap->error if we don't want to use the streaming callback for this DIME attachment */
    const char *file;
    struct mime_server_handle *handle = (struct mime_server_handle *)soap_malloc(soap, sizeof(struct mime_server_handle));
    if (!handle)
    { soap->error = SOAP_EOM;
        return NULL;
    }
    /* Create a new file */
    file = tempnam(TMPDIR, "data");
 
    /* The file name is also the key */
    handle->key = soap_strdup(soap, file);
    handle->fd = fopen(file, "wb");
    free((void*)file);
    if (!handle->fd)
    { soap->error = soap_sender_fault(soap, "Cannot save data to file", handle->key);
        soap->errnum = errno; /* get reason */
        return NULL;
    }
    fprintf(stderr, "Saving file %s type %s\n", handle->key, type?type:"");
    return (void*)handle;
}

The red code above uses the C function tempnam to generate a temporary file name for saving attachments. In actual implementation, You can classify and manage attachments based on the MIME type.

Section 3 test MTOM using SoapUI

For example, add several Attachments to Attachments and use cid to reference Attachments in the xop: include attribute href of the soap request,

The request result is:

The preceding example uses the MTOM request and the returned result is a base64-encoded binary format. Similarly, you can use base64 encoding to obtain the attachment Message format in the MTOM mode, as shown below:

 

Section 4 Use fidder to obtain SoapUI packets

The proxy function of the two softwares required for obtaining SoapUI messages using Fidder.

4.1 SoapUI settings

Step 1: Open the menu File ---> Preferences

Step 2: select the Proxy Setting tab for the following settings:

4.2 Fidder settings

Step 1: Tools-> Options

Step 2: Open the Connections tab

 

In principle, SoapUI sends external requests to the proxy through port 8888, while Fidder listens to proxy events on port 8888. The following is the message sent by SoapUI intercepted by Fidder: