SOAP_MACRO run-time flags

This module defines the SOAP_MACRO run-time soap_mode flags to set the engine mode. More...

Macros
#define	SOAP_IO   0x00000003
	soap_mode IO flags mask to check for SOAP_IO_FLUSH, SOAP_IO_BUFFER, SOAP_IO_STORE, SOAP_IO_CHUNK (for internal use only) More...
#define	SOAP_IO_FLUSH   0x00000000
	soap_mode IO output flag value to flush the message sent immediately without buffering (the default mode), do not combine this flag with SOAP_IO_BUFFER, SOAP_IO_STORE, SOAP_IO_CHUNK More...
#define	SOAP_IO_BUFFER   0x00000001
	soap_mode IO output flag value to buffer the message sent in packets of size SOAP_BUFLEN, do not combine this flag with SOAP_IO_FLUSH, SOAP_IO_STORE, SOAP_IO_CHUNK More...
#define	SOAP_IO_STORE   0x00000002
	soap_mode IO output flag value to store messages temporarily before transmission, e.g. to determine message length for transmission over HTTP instead of chunking or two-phase message sends, do not combine this flag with SOAP_IO_FLUSH, SOAP_IO_BUFFER, SOAP_IO_CHUNK More...
#define	SOAP_IO_CHUNK   0x00000003
	soap_mode IO output flag value to send HTTP chunked messages, buffers the message in packets of size SOAP_BUFLEN, do not combine this flag with SOAP_IO_FLUSH, SOAP_IO_BUFFER, SOAP_IO_STORE More...
#define	SOAP_IO_UDP   0x00000004
	soap_mode IO input/output flag value to use UDP datagrams, message size is limited to UDP packet size More...
#define	SOAP_IO_LENGTH   0x00000008
	soap_mode IO output flag value to calculate message length when sending a message without transmission (for internal use only) More...
#define	SOAP_IO_KEEPALIVE   0x00000010
	soap_mode IO input and output flag value to keep the socket connection alive for SOAP_MAXKEEPALIVE message exchanges per connection (100 by default), enabling HTTP keep-alive connection persistence More...
#define	SOAP_ENC   0x00000FFF
	soap_mode ENC flags mask (for internal use only) More...
#define	SOAP_ENC_LATIN   0x00000020
	soap_mode ENC input flag value to receive ISO-8859-1 encoded messages (automatically detected when receiving XML) More...
#define	SOAP_ENC_PLAIN   0x00000040
	soap_mode ENC input/output flag value to omit the HTTP headers from messages sent and disable detection and parsing of HTTP headers in messages received More...
#define	SOAP_ENC_XML
	soap_mode ENC input/output flag (deprecated, same as SOAP_ENC_PLAIN for backward compatibility) More...
#define	SOAP_ENC_DIME   0x00000080
	soap_mode ENC output flag value to enable DIME attachments (for internal use only) More...
#define	SOAP_ENC_MIME   0x00000100
	soap_mode ENC output flag value to enable MIME attachments in messages to be sent, receiving is automatic More...
#define	SOAP_ENC_MTOM   0x00000200
	soap_mode ENC output flag value to enable MTOM XOP attachments in messages to be sent, receiving is automatic More...
#define	SOAP_ENC_ZLIB   0x00000400
	soap_mode ENC output flag value to compress messages sent, requires zlib enabled with compile-time flag WITH_GZIP (or WITH_ZLIB for compression limited to "compress"), detection of compressed messages received and decompression of the messages is automatic More...
#define	SOAP_ENC_SSL   0x00000800
	soap_mode ENC input/output flag value to enable TLS/SSL, e.g. HTTPS, requires OpenSSL, GNUTLS or WolfSSL enabled with compile-time flag WITH_OPENSSL, WITH_GNUTLS, or WITH_WOLFSSL (flag for internal use only) More...
#define	SOAP_XML_STRICT   0x00001000
	soap_mode XML input flag value to enable strict XML validation of messages received More...
#define	SOAP_XML_INDENT   0x00002000
	soap_mode XML output flag value to enable XML (and JSON) message indentation in messages sent More...
#define	SOAP_XML_IGNORENS   0x00004000
	soap_mode XML input flag value to ignore XML namespaces in messages received More...
#define	SOAP_XML_DEFAULTNS   0x00008000
	soap_mode XML output flag value to send XML messages with XML default namespaces for elements instead of namespace-qualified elements More...
#define	SOAP_XML_CANONICAL   0x00010000
	soap_mode XML output flag value to send XML messages in exclusive canonical format as per W3C XML C14N standards, use with the soap::c14ninclude and soap::c14nexclude strings to control the prefixes that are subject to canonicalization by including or excluding specific prefixes More...
#define	SOAP_XML_CANONICAL_NA   0x00800000
	soap_mode XML output flag value to send XML messages in exclusive canonical format as per W3C XML C14N standards, use with the soap::c14ninclude and soap::c14nexclude strings to control the prefixes that are subject to canonicalization by including or excluding specific prefixes More...
#define	SOAP_XML_TREE   0x00020000
	soap_mode XML input/output flag value to serialize C/C++ data structures as XML trees without id-href or id-ref multi-references, duplicates co-referenced data in the XML output and automatically breaks data structure cycles to prevent infinite serialization loops, ignores id and href/ref reference attributes in messages received, this flag is the opposite of SOAP_XML_GRAPH More...
#define	SOAP_XML_GRAPH   0x00020000
	soap_mode XML input/output flag value to serialize C/C++ (cyclic) data structures in XML with id-ref references for co-referenced data and to accurately serialize data structure cycles, accept id-ref references in XML received to (re)construct the C/C++ (co-referenced and cyclic) data structures, this flag is the opposite of SOAP_XML_TREE More...
#define	SOAP_XML_NIL   0x00040000
	soap_mode XML output flag value to serialize C/C++ NULL pointers in XML as elements with attribute xsi:nil="true" More...
#define	SOAP_XML_NOTYPE   0x00080000
	soap_mode XML output flag value to serialize C/C++ data structures in XML without xsi:type attributes, even when this may be necessary to distinguish base from derived data types More...
#define	SOAP_XML_DOM   0x10000000
	soap_mode XML input/output flag value to enable DOM node tree construction of the XML received and sent, requires compile-time flag WITH_DOM More...
#define	SOAP_DOM_ASIS   0x00400000
	soap_mode DOM output flag value to disable reformatting of the DOM node tree in XML, displaying the DOM in XML exactly as is More...
#define	SOAP_DOM_NODE   0x00200000
	soap_mode DOM input flag value to always attempt to deserialize embedded serializable C/C++ data structures into the DOM node tree based on matching element name to C/C++ type names and by matching xsi:type attributes when present, the opposite of SOAP_DOM_TREE More...
#define	SOAP_DOM_TREE   0x00100000
	soap_mode DOM input flag value to ignore id and xsi:type XML attributes and disables deserialization of serializable C/C++ data structures into the DOM node tree, the opposite of SOAP_DOM_NODE More...
#define	SOAP_C_NOIOB   0x01000000
	soap_mode input flag value to ignore array items that are out of bounds when deserializing fixed-size arrays, instead of producing SOAP_IOB errors More...
#define	SOAP_C_UTFSTRING   0x02000000
	soap_mode input/output flag value to serialize and deserialize 8-bit C/C++ strings containing UTF-8 encoded Unicode characters More...
#define	SOAP_C_MBSTRING   0x04000000
	soap_mode input/output flag value to enable multibyte character support for 8-bit character strings with wctomb and mbtowc using the current locale More...
#define	SOAP_C_NILSTRING   0x08000000
	soap_mode input/output flag value to serialize empty strings as elements with attribute xsi:nil="true" More...
#define	SOAP_MIME_POSTCHECK   0x40000000
	soap_mode MIME input flag value to check and process additional MIME attachments (for internal use only) More...
#define	SOAP_SEC_WSUID   0x80000000
	soap_mode SEC output flag value to add wsu:Id attributes to signed parts of messages sent and signed with WS-Security (for internal use only) More...

Typedefs
typedef int	soap_mode
	The soap_mode flags to initialize the soap context, flags can be combined with | (bit-wise or) More...

Detailed Description

This module defines the SOAP_MACRO run-time soap_mode flags to set the engine mode.

This module defines the following soap_mode flags:

• SOAP_C_MBSTRING
• SOAP_C_NILSTRING
• SOAP_C_NOIOB
• SOAP_C_UTFSTRING
• SOAP_DOM_ASIS
• SOAP_DOM_NODE
• SOAP_DOM_TREE
• SOAP_ENC
• SOAP_ENC_DIME
• SOAP_ENC_LATIN
• SOAP_ENC_MIME
• SOAP_ENC_MTOM
• SOAP_ENC_PLAIN
• SOAP_ENC_SSL
• SOAP_ENC_XML
• SOAP_ENC_ZLIB
• SOAP_IO
• SOAP_IO_BUFFER
• SOAP_IO_CHUNK
• SOAP_IO_FLUSH
• SOAP_IO_KEEPALIVE
• SOAP_IO_LENGTH
• SOAP_IO_STORE
• SOAP_IO_UDP
• SOAP_MIME_POSTCHECK
• SOAP_SEC_WSUID
• SOAP_XML_CANONICAL
• SOAP_XML_CANONICAL_NA
• SOAP_XML_DEFAULTNS
• SOAP_XML_DOM
• SOAP_XML_GRAPH
• SOAP_XML_IGNORENS
• SOAP_XML_INDENT
• SOAP_XML_NIL
• SOAP_XML_NOTYPE
• SOAP_XML_STRICT
• SOAP_XML_TREE

Macro Definition Documentation

#define SOAP_C_MBSTRING   0x04000000

soap_mode input/output flag value to enable multibyte character support for 8-bit character strings with wctomb and mbtowc using the current locale

This flag requires macros HAVE_WCTOMB and HAVE_MBTOWC to be defined. Otherwise, this flag has no effect.

Warning

the wctomb and mbtowc functions are not thread safe. It is recommended to use SOAP_C_UTFSTRING instead of SOAP_C_MBSTRING. SOAP_C_UTFSTRING idoes not depend on the current locale.

See also

SOAP_C_UTFSTRING.

#define SOAP_C_NILSTRING   0x08000000

soap_mode input/output flag value to serialize empty strings as elements with attribute xsi:nil="true"

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_C_NILSTRING); // elements with empty strings have <i>`xsi:nil="true"`</i>

#define SOAP_C_NOIOB   0x01000000

soap_mode input flag value to ignore array items that are out of bounds when deserializing fixed-size arrays, instead of producing SOAP_IOB errors

Example:

struct ns__webmethodResponse
{
  float coordinates[3];
};
int ns__webmethod(float x, struct ns__webmethodResponse *out);

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_C_NOIOB);
struct ns__webmethodResponse result;
... //
if (soap_call_ns__webmethod(soap, endpoint, NULL, 3, &result))
  ... // deserializing more than 3 array items does not produce a SOAP_IOB error here
else
  ... // success

#define SOAP_C_UTFSTRING   0x02000000

soap_mode input/output flag value to serialize and deserialize 8-bit C/C++ strings containing UTF-8 encoded Unicode characters

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_C_UTFSTRING);

#define SOAP_DOM_ASIS   0x00400000

soap_mode DOM output flag value to disable reformatting of the DOM node tree in XML, displaying the DOM in XML exactly as is

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_DOM_ASIS);
soap_dom_element *dom = soap_new_xsd__anyType(soap); // allocate dom
if ((soap->recvfd = open("doc1.xml", O_RDONLY)) == 0 || soap_read_xsd__anyType(soap, dom))
  ... // an error occurred
if ((soap->sendfd = open("doc2.xml", O_CREAT | O_RDWR, 0644)) == 0 || soap_write_xsd__anyType(soap, dom))
  ... // an error occurred
close(soap->recvfd);
soap->recvfd = 0;
close(soap->sendfd);
soap->sendfd = 1;

This example requires the soapC.cpp source code generated with soapcpp2 from gsoap/import/dom.h as (imported) input in order to use soap_new_xsd__anyType and soap_write_xsd__anyType.

See also

SOAP_DOM_NODE, SOAP_DOM_TREE and the gSOAP XML DOM API documentation.

#define SOAP_DOM_NODE   0x00200000

soap_mode DOM input flag value to always attempt to deserialize embedded serializable C/C++ data structures into the DOM node tree based on matching element name to C/C++ type names and by matching xsi:type attributes when present, the opposite of SOAP_DOM_TREE

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_DOM_NODE);
soap_dom_element *dom = soap_new_xsd__anyType(soap); // allocate dom
soap_dom_element *elt = soap_new_xsd__anyType(soap); // allocate child element
int num = 123;
soap_elt(dom, NULL, "data");                     // create <data> element
soap_elt_node(elt, (void*)&num, SOAP_TYPE_int)); // with value 123 serialized as child
soap_add_elt(dom, elt);
if (soap_write_xsd__anyType(soap, dom))
  ... // error, could not write

This example requires the soapC.cpp source code generated with soapcpp2 from gsoap/import/dom.h as (imported) input in order to use soap_new_xsd__anyType and soap_write_xsd__anyType.

See also

SOAP_DOM_ASIS, SOAP_DOM_TREE and the gSOAP XML DOM API documentation.

#define SOAP_DOM_TREE   0x00100000

soap_mode DOM input flag value to ignore id and xsi:type XML attributes and disables deserialization of serializable C/C++ data structures into the DOM node tree, the opposite of SOAP_DOM_NODE

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_DOM_TREE);
soap_dom_element *dom = soap_new_xsd__anyType(soap); // allocate dom
if ((soap->recvfd = open("doc.xml", O_RDONLY)) == 0 || soap_read_xsd__anyType(soap, dom))
  ... // an error occurred
close(soap->recvfd);
soap->recvfd = 0;

This example requires the soapC.cpp source code generated with soapcpp2 from gsoap/import/dom.h as (imported) input in order to use soap_new_xsd__anyType, soap_read_xsd__anyType and soap_write_xsd__anyType.

See also

SOAP_DOM_ASIS, SOAP_DOM_NODE and the gSOAP XML DOM API documentation.

#define SOAP_ENC   0x00000FFF

soap_mode ENC flags mask (for internal use only)

#define SOAP_ENC_DIME   0x00000080

soap_mode ENC output flag value to enable DIME attachments (for internal use only)

Examples:

#include "soapH.h"

struct soap *soap = soap_new();
struct _xop__Include data;                                  // here we're using gsoap/import/xop.h to store a blob of raw data
data.__ptr = (unsigned char*)soap_malloc(soap, 1024);       // allocate 1024 bytes on the managed heap
memcpy(data.__ptr, image_data);                             // copy an image (or we could just assign to data.__ptr)
data.__size = 1024;                                         // 1024 bytes of data
data.id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
data.type = "image/png";                                    // attachment type
data.options = soap_dime_option(soap, 0, "Picture.png");    // DIME option 0 = "Picture.png" to store file name
... // add data to the message and then send it, which will transmit the data as an attachment

#include "soapH.h"

struct soap *soap = soap_new();
unsigned char *ptr = (unsigned char*)image_data;                   // image data to attach
size_t size = 1024;                                                // 1024 bytes of data
const char *id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
const char *type = "image/png";                                    // attachment type
if (soap_set_dime_attachment(soap, ptr, size, type, id, 0, "Picture.png"))
  ... // error attaching
... // send a message, image is attached

The SOAP_ENC_DIME flag is automatically set when attachments are present in the message to be sent or when a message with DIME attachments is received and does not need to be set explicitly.

DIME attachment sizes are limited to SOAP_MAXDIMESIZE, which is a compile-time constant that can be changed.

See also

SOAP_ENC_MIME, SOAP_ENC_DIME, DIME attachments.

#define SOAP_ENC_LATIN   0x00000020

soap_mode ENC input flag value to receive ISO-8859-1 encoded messages (automatically detected when receiving XML)

#define SOAP_ENC_MIME   0x00000100

soap_mode ENC output flag value to enable MIME attachments in messages to be sent, receiving is automatic

The MTOM specification requires SOAP 1.2.

Examples:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_ENC_MIME);               // enable MIME attachments, not DIME or MTOM
struct _xop__Include data;                                  // here we're using gsoap/import/xop.h to store a blob of raw data
data.__ptr = (unsigned char*)soap_malloc(soap, 1024);       // allocate 1024 bytes on the managed heap
memcpy(data.__ptr, image_data);                             // copy an image (or we could just assign to data.__ptr)
data.__size = 1024;                                         // 1024 bytes of data
data.id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
data.type = "image/png";                                    // attachment type
data.options = "Picture";                                   // attachment description
... // add data to the message and then send it

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_ENC_MIME);                      // enable MIME attachments, not DIME or MTOM
unsigned char *ptr = (unsigned char*)image_data;                   // image data to attach
size_t size = 1024;                                                // 1024 bytes of data
const char *id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
const char *type = "image/png";                                    // attachment type
if (soap_set_mime_attachment(soap, ptr, size, SOAP_MIME_BINARY, type, id, "No location", "Picture))
  ... // error attaching
... // send a message, image is attached
soap_clr_mime(soap);

To enable MIME on the fly to return MIME attachments in the message sent:

soap_set_omode(soap, SOAP_ENC_MIME);
... // populate data and send

To disable:

soap_clr_omode(soap, SOAP_ENC_MIME);

See also

SOAP_ENC_DIME, SOAP_ENC_MTOM, MIME attachments.

#define SOAP_ENC_MTOM   0x00000200

soap_mode ENC output flag value to enable MTOM XOP attachments in messages to be sent, receiving is automatic

Examples:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_ENC_MTOM);               // enable MTOM attachments, not DIME
struct _xop__Include data;                                  // here we're using gsoap/import/xop.h to store a blob of raw data
data.__ptr = (unsigned char*)soap_malloc(soap, 1024);       // allocate 1024 bytes on the managed heap
memcpy(data.__ptr, image_data);                             // copy an image (or we could just assign to data.__ptr)
data.__size = 1024;                                         // 1024 bytes of data
data.id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
data.type = "image/png";                                    // attachment type
data.options = "Picture";                                   // attachment description
... // add data to the message and then send it

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_ENC_MTOM);                      // enable MTOM attachments, not DIME
unsigned char *ptr = (unsigned char*)image_data;                   // image data to attach
size_t size = 1024;                                                // 1024 bytes of data
const char *id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
const char *type = "image/png";                                    // attachment type
if (soap_set_mime_attachment(soap, ptr, size, SOAP_MIME_BINARY, type, id, "No location", "Picture))
  ... // error attaching
... // send a message, image is attached
soap_clr_mime(soap);

To enable MTOM on the fly to return MTOM attachments in the message sent:

soap_set_omode(soap, SOAP_ENC_MTOM);
... // populate data and send

To disable:

soap_clr_omode(soap, SOAP_ENC_MTOM);

See also

SOAP_ENC_DIME, SOAP_ENC_MIME, MTOM attachments.

#define SOAP_ENC_PLAIN   0x00000040

soap_mode ENC input/output flag value to omit the HTTP headers from messages sent and disable detection and parsing of HTTP headers in messages received

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_ENC_PLAIN); // no HTTP

#define SOAP_ENC_SSL   0x00000800

soap_mode ENC input/output flag value to enable TLS/SSL, e.g. HTTPS, requires OpenSSL, GNUTLS or WolfSSL enabled with compile-time flag WITH_OPENSSL, WITH_GNUTLS, or WITH_WOLFSSL (flag for internal use only)

#define SOAP_ENC_XML

soap_mode ENC input/output flag (deprecated, same as SOAP_ENC_PLAIN for backward compatibility)

#define SOAP_ENC_ZLIB   0x00000400

soap_mode ENC output flag value to compress messages sent, requires zlib enabled with compile-time flag WITH_GZIP (or WITH_ZLIB for compression limited to "compress"), detection of compressed messages received and decompression of the messages is automatic

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_ENC_ZLIB); // HTTP compression

#define SOAP_IO   0x00000003

soap_mode IO flags mask to check for SOAP_IO_FLUSH, SOAP_IO_BUFFER, SOAP_IO_STORE, SOAP_IO_CHUNK (for internal use only)

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_IO_CHUNK);
if ((soap->omode & SOAP_IO) == SOAP_IO_CHUNK)
  ... // HTTP chunking is enabled

#define SOAP_IO_BUFFER   0x00000001

soap_mode IO output flag value to buffer the message sent in packets of size SOAP_BUFLEN, do not combine this flag with SOAP_IO_FLUSH, SOAP_IO_STORE, SOAP_IO_CHUNK

#define SOAP_IO_CHUNK   0x00000003

soap_mode IO output flag value to send HTTP chunked messages, buffers the message in packets of size SOAP_BUFLEN, do not combine this flag with SOAP_IO_FLUSH, SOAP_IO_BUFFER, SOAP_IO_STORE

Note

SOAP_IO_CHUNK is preferable to use compared to SOAP_IO_STORE, because SOAP_IO_STORE requires more memory and increases response time latency due to the overhead of storing the entire message before transmission.

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_IO_CHUNK); // enable HTTP chunking

#define SOAP_IO_FLUSH   0x00000000

soap_mode IO output flag value to flush the message sent immediately without buffering (the default mode), do not combine this flag with SOAP_IO_BUFFER, SOAP_IO_STORE, SOAP_IO_CHUNK

#define SOAP_IO_KEEPALIVE   0x00000010

soap_mode IO input and output flag value to keep the socket connection alive for SOAP_MAXKEEPALIVE message exchanges per connection (100 by default), enabling HTTP keep-alive connection persistence

This flag activates HTTP connection persistence for client and server applications. The input and output mode flags should both be set to enable HTTP connection persistance.

Client applications can request HTTP persistance with this flag enabled and may indicate the end of a sequence of messages by disabling this flag immediately prior to the last message exchange with a server, which allows the server to gracefully close the connection. If the client does not disable this flag, the server will keep the connection open until the connection is reset or times out.

Stand-alone server applications should be multi-threaded to use this flag, because iterative servers cannot serve other clients while connected to one client. Stand-alone multi-threaded server applications should also use timeouts and limit the number of messages exchanged in a keep-alive connection with soap::max_keep_alive, which is set to SOAP_MAXKEEPALIVE (the value is 100 by default).

Warning

Do not use SOAP_IO_KEEPALIVE with CGI and FastCGI applications.

Examples:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_IO_KEEPALIVE); // enable HTTP keep-alive
soap->max_keep_alive = 50;                        // serve 50 max keep-alive exchanges (SOAP_MAXKEEPALIVE by default)
... // serve requests with soap_bind, soap_accept, soap_ssl_accept, and soap_serve

#include "soapH.h"

struct soap *soap = soap_new();
soap_set_mode(soap, SOAP_IO_KEEPALIVE);           // keep connection to the server open
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
  soap_print_fault(soap, stderr);
else
  ... // success
soap_clr_mode(soap, SOAP_IO_KEEPALIVE);           // connection is still open, but close it afterwards
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
  soap_print_fault(soap, stderr);
else
  ... // success

See also

soap::keep_alive, soap::max_keep_alive, SOAP_MAXKEEPALIVE.

#define SOAP_IO_LENGTH   0x00000008

soap_mode IO output flag value to calculate message length when sending a message without transmission (for internal use only)

See also

soap_begin_count, soap_end_count.

#define SOAP_IO_STORE   0x00000002

soap_mode IO output flag value to store messages temporarily before transmission, e.g. to determine message length for transmission over HTTP instead of chunking or two-phase message sends, do not combine this flag with SOAP_IO_FLUSH, SOAP_IO_BUFFER, SOAP_IO_CHUNK

When set as input-mode flag, forces all messages sent to be temporarily stored before transmission. When set as output-mode flag, forces only the next message to be temporarily stored before transmission.

Note

SOAP_IO_CHUNK is preferable over SOAP_IO_STORE, because SOAP_IO_STORE requires more memory and increases response time latency due to the overhead of storing the entire message before transmission.

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_IO_STORE); // store messages temporarily before transmission

#define SOAP_IO_UDP   0x00000004

soap_mode IO input/output flag value to use UDP datagrams, message size is limited to UDP packet size

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_IO_UDP); // use UDP

See also

SOAP/XML over UDP.

#define SOAP_MIME_POSTCHECK   0x40000000

soap_mode MIME input flag value to check and process additional MIME attachments (for internal use only)

Used by soap_post_check_mime_attachments and soap_check_mime_attachments.

#define SOAP_SEC_WSUID   0x80000000

soap_mode SEC output flag value to add wsu:Id attributes to signed parts of messages sent and signed with WS-Security (for internal use only)

#define SOAP_XML_CANONICAL   0x00010000

soap_mode XML output flag value to send XML messages in exclusive canonical format as per W3C XML C14N standards, use with the soap::c14ninclude and soap::c14nexclude strings to control the prefixes that are subject to canonicalization by including or excluding specific prefixes

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_CANONICAL); // XML canonicalization, exclusive by default
soap->c14ninclude = "*";                           // optional: make all prefixes inclusive, i.e. inclusive canonicalization

This flag changes the following example XML fragment:

<a:foo xmlns:b="http://example.org" qux="b" b:quux="c" baz="a" xmlns:a="http://www.w3.org">
  <bar xmlns:c="http://www.ietf.org"></bar>
</a:foo>

into the following exclusive C14N fragment:

<a:foo xmlns:a="http://www.w3.org" xmlns:b="http://example.org" baz="a" qux="b" b:quux="c">
  <bar></bar>
</a:foo>

Sending XML is slowed down by canonicalization. Furthermore, messages may or may not be reduced in size, depending on the additional xmlns bindings generated for local element scopes. Consider for example the following message:

<a:foo xmlns:a="http://www.w3.org" xmlns:b="http://example.org">
  <b:bar>1</b:bar>
  <b:bar>2</b:bar>
  <b:bar>3</b:bar>
</a:foo>

The message is larger when canonicalized:

<a:foo xmlns:a="http://www.w3.org">
  <b:bar xmlns:b="http://example.org">1</b:bar>
  <b:bar xmlns:b="http://example.org">2</b:bar>
  <b:bar xmlns:b="http://example.org">3</b:bar>
</a:foo>

Note

Because the W3C XML C14N (canonicalization) standards do not cover QName values, inclusive and exclusive C14N appear to be broken when QNames are used. XML C14N retains xmlns bindings of utilized elements and attributes only, which means that xmlns bindings for prefixes in QNames may be lost in the canonicalization process. The gSOAP toolkit implements XML C14N with QName normalization to prevent this loss. Losing xmlns bindings for QName prefixes not only invalidates XML messages, but may also lead to incorrectly bound prefixes to xmlns bindings used in the outer scope of the canonicalized XML. This poses a security threat when malicious xmlns bindings are placed in the outer scope to capture unbound QName prefix bindings. The SOAP_XML_CANONICAL_NA mode flag omits QName canonicalization.

Example:

<a:foo xmlns:a="http://www.w3.org" xmlns:b="http://example.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <bar xsi:type="a:Bar" xmlns:a="http://example.org"></bar>
</a:foo>

This example XML fragment is canonicalized with SOAP_XML_CANONICAL as:

<a:foo xmlns:a="http://www.w3.org">
  <bar xmlns:a="http://example.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="a:Bar"></bar>
</a:foo>

The example XML fragment is canonicalized with SOAP_XML_CANONICAL | SOAP_XML_CANONICAL_NA as per W3C XML exclusive C14N as:

<a:foo xmlns:a="http://www.w3.org">
  <bar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="a:Bar"></bar>
</a:foo>

Note that prefix a in "a:Bar" is now bound to "http://www.w3.org" captured by the outer xmlns:a="http://www.w3.org". XML libraries may rename prefixes to prevent capturing. The gSOAP serializers do not reuse prefixes, meaning that this problem cannot occur. However, this does not prevent the namespace prefix to become lost when exclusive C14N is used and namespace bindings are removed because prefixes are not visibly utilized.

See also

SOAP_XML_CANONICAL_NA.

#define SOAP_XML_CANONICAL_NA   0x00800000

soap_mode XML output flag value to send XML messages in exclusive canonical format as per W3C XML C14N standards, use with the soap::c14ninclude and soap::c14nexclude strings to control the prefixes that are subject to canonicalization by including or excluding specific prefixes

Must be used in combination with SOAP_XML_CANONICAL_NA to emit XML in canonical form such that namespace prefixes in QName values are ignored. Recommended is to only use SOAP_XML_CANONICAL which is more secure, see the SOAP_XML_CANONICAL notes.

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_CANONICAL_NA);
soap->c14ninclude = "*"; // make all prefixes inclusive, i.e. inclusive canonicalization

See also

SOAP_XML_CANONICAL.

#define SOAP_XML_DEFAULTNS   0x00008000

soap_mode XML output flag value to send XML messages with XML default namespaces for elements instead of namespace-qualified elements

Warning

This mode is not recommended for SOAP RPC encoding style messaging. Optionally use this mode with XML, XML REST, and SOAP/XML document/literal style messages.

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_DEFAULTNS); // use XML default namespaces with xmlns="..."

This flag changes the following example XML fragment:

<ns:foo xmlns:ns="http://example.org" qux="a" ns:quux="a">
  <ns:bar>y</ns:bar>
  <baz>z<baz>
</ns:foo>

into the following fragment with default namespaces for XML elements:

<foo xmlns="http://example.org" xmlns:ns="http://example.org" qux="a" ns:quux="a">
  <bar>y<bar>
  <baz xmlns="">z<baz>
</foo>

Qualified XML element names are replaced by unqualified element names. Qualified XML attribute names are not affected and require a prefix with an XML namespace binding. The SOAP_XML_DEFAULTNS mode flag affects serialization performance somewhat negatively. To produce normalized cleaner XML use the SOAP_XML_CANONICAL mode flag, but this further negatively affects serialization performance.

See also

WITH_NOEMPTYNAMESPACES, SOAP_XML_CANONICAL.

#define SOAP_XML_DOM   0x10000000

soap_mode XML input/output flag value to enable DOM node tree construction of the XML received and sent, requires compile-time flag WITH_DOM

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_DOM);
... // call an XML service operation that deserializes the response
if (soap->dom) // we also got a DOM
{
  const struct soap_dom_element *elt = soap->dom;
  ... // inspect the DOM using the DOM API functions (see the gSOAP [XML DOM API documentation](../../dom/html/index.html))
}

#define SOAP_XML_GRAPH   0x00020000

soap_mode XML input/output flag value to serialize C/C++ (cyclic) data structures in XML with id-ref references for co-referenced data and to accurately serialize data structure cycles, accept id-ref references in XML received to (re)construct the C/C++ (co-referenced and cyclic) data structures, this flag is the opposite of SOAP_XML_TREE

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_GRAPH); // id-ref multi-reference serialization

Note

This mode flag is not usable when the engine is compiled with WITH_NOIDREF.

See also

SOAP_XML_TREE.

#define SOAP_XML_IGNORENS   0x00004000

soap_mode XML input flag value to ignore XML namespaces in messages received

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_IGNORENS); // ignore xmlns bindings in XML

#define SOAP_XML_INDENT   0x00002000

soap_mode XML output flag value to enable XML (and JSON) message indentation in messages sent

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_INDENT); // indent XML

#define SOAP_XML_NIL   0x00040000

soap_mode XML output flag value to serialize C/C++ NULL pointers in XML as elements with attribute xsi:nil="true"

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_NIL); // emit NULL pointers as empty elements with xsi:nil="true"

#define SOAP_XML_NOTYPE   0x00080000

soap_mode XML output flag value to serialize C/C++ data structures in XML without xsi:type attributes, even when this may be necessary to distinguish base from derived data types

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_NOTYPE); // no xsi:type attributes ever

#define SOAP_XML_STRICT   0x00001000

soap_mode XML input flag value to enable strict XML validation of messages received

Warning

This mode is not recommended for SOAP RPC encoding style messaging. XML, XML REST, and SOAP/XML document/literal style messages can be validated.

Alternatively, use soapcpp2 -s to generate stub and skeleton functions that perform strict XML validation checks.

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_STRICT); // strict XML validation

See also

WITH_REPLACE_ILLEGAL_UTF8, SOAP_UNKNOWN_UNICODE_CHAR.

#define SOAP_XML_TREE   0x00020000

soap_mode XML input/output flag value to serialize C/C++ data structures as XML trees without id-href or id-ref multi-references, duplicates co-referenced data in the XML output and automatically breaks data structure cycles to prevent infinite serialization loops, ignores id and href/ref reference attributes in messages received, this flag is the opposite of SOAP_XML_GRAPH

Example:

#include "soapH.h"

struct soap *soap = soap_new1(SOAP_XML_TREE); // no id-href and id-ref multi-reference serialization

Note

This mode flag is always active when the engine is compiled with WITH_NOIDREF.

See also

SOAP_XML_GRAPH, WITH_NOIDREF.

Typedef Documentation

typedef int soap_mode

The soap_mode flags to initialize the soap context, flags can be combined with | (bit-wise or)

The soap_mode flags are:

• SOAP_C_MBSTRING
• SOAP_C_NILSTRING
• SOAP_C_NOIOB
• SOAP_C_UTFSTRING
• SOAP_DOM_ASIS
• SOAP_DOM_NODE
• SOAP_DOM_TREE
• SOAP_ENC
• SOAP_ENC_DIME
• SOAP_ENC_LATIN
• SOAP_ENC_MIME
• SOAP_ENC_MTOM
• SOAP_ENC_PLAIN
• SOAP_ENC_SSL
• SOAP_ENC_XML
• SOAP_ENC_ZLIB
• SOAP_IO
• SOAP_IO_BUFFER
• SOAP_IO_CHUNK
• SOAP_IO_FLUSH
• SOAP_IO_KEEPALIVE
• SOAP_IO_LENGTH
• SOAP_IO_STORE
• SOAP_IO_UDP
• SOAP_MIME_POSTCHECK
• SOAP_SEC_WSUID
• SOAP_XML_CANONICAL
• SOAP_XML_CANONICAL_NA
• SOAP_XML_DEFAULTNS
• SOAP_XML_DOM
• SOAP_XML_GRAPH
• SOAP_XML_IGNORENS
• SOAP_XML_INDENT
• SOAP_XML_NIL
• SOAP_XML_NOTYPE
• SOAP_XML_STRICT
• SOAP_XML_TREE