Genivia - SOAP_MACRO run-time flags

|  | Home | Documentation | SOAP_MACRO run-time flags updated Mon Apr 22 2024 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Macros | Typedefs
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:

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

into the following exclusive C14N fragment:

1 <a:foo xmlns:a="http://www.w3.org" xmlns:b="http://example.org" baz="a" qux="b" b:quux="c">
2 <bar></bar>
3 </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:

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

The message is larger when canonicalized:

1 <a:foo xmlns:a="http://www.w3.org">
2 <b:bar xmlns:b="http://example.org">1</b:bar>
3 <b:bar xmlns:b="http://example.org">2</b:bar>
4 <b:bar xmlns:b="http://example.org">3</b:bar>
5 </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:

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

This example XML fragment is canonicalized with `SOAP_XML_CANONICAL` as:

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

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

1 <a:foo xmlns:a="http://www.w3.org">
2 <bar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="a:Bar"></bar>
3 </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:

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

into the following fragment with default namespaces for XML elements:

1 <foo xmlns="http://example.org" xmlns:ns="http://example.org" qux="a" ns:quux="a">
2 <bar>y<bar>
3 <baz xmlns="">z<baz>
4 </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`