|  | Home | Documentation | SOAP_MACRO run-time flags updated by Robert van Engelen |

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)
#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_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_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
#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
#define | SOAP_IO_UDP 0x00000004
| soap_mode IO input/output flag value to use UDP datagrams, message size is limited to UDP packet size
#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)
#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
#define | SOAP_ENC 0x00000FFF
| soap_mode ENC flags mask (for internal use only)
#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_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
#define | SOAP_ENC_XML
| soap_mode ENC input/output flag (deprecated, same as #SOAP_ENC_PLAIN for backward compatibility)
#define | SOAP_ENC_DIME 0x00000080
| soap_mode ENC output flag value to enable DIME attachments (for internal use only)
#define | SOAP_ENC_MIME 0x00000100
| soap_mode ENC output flag value to enable MIME attachments in messages to be sent, receiving is automatic
#define | SOAP_ENC_MTOM 0x00000200
| soap_mode ENC output flag value to enable MTOM XOP attachments in messages to be sent, receiving is automatic
#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
#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_XML_STRICT 0x00001000
| soap_mode XML input flag value to enable strict XML validation of messages received
#define | SOAP_XML_INDENT 0x00002000
| soap_mode XML output flag value to enable XML (and JSON) message indentation in messages sent
#define | SOAP_XML_IGNORENS 0x00004000
| soap_mode XML input flag value to ignore XML namespaces in messages received
#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
#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
#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
#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 and ignores these attributes during deserialization.
#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,
#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"
#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
#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
#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
#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
#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
#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
#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
#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
#define | SOAP_C_NILSTRING 0x08000000
| soap_mode input/output flag value to serialize empty strings as elements with attribute xsi:nil="true"
#define | SOAP_MIME_POSTCHECK 0x40000000
| soap_mode MIME input flag value to check and process additional MIME attachments (for internal use only)
#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)

## Typedefs

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

## 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

## ◆ SOAP_C_MBSTRING

#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.

## ◆ SOAP_C_NILSTRING

#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>
SOAP_C_NILSTRING
#define SOAP_C_NILSTRING
soap_mode input/output flag value to serialize empty strings as elements with attribute xsi:nil="true...
Definition stdsoap2.h:2309
soap
Context with the engine state.
Definition stdsoap2.h:2929

## ◆ SOAP_C_NOIOB

#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
SOAP_C_NOIOB
#define SOAP_C_NOIOB
soap_mode input flag value to ignore array items that are out of bounds when deserializing fixed-size...
Definition stdsoap2.h:2275

## ◆ SOAP_C_UTFSTRING

#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);
SOAP_C_UTFSTRING
#define SOAP_C_UTFSTRING
soap_mode input/output flag value to serialize and deserialize 8-bit C/C++ strings containing UTF-8 e...
Definition stdsoap2.h:2287

## ◆ SOAP_DOM_ASIS

#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;
SOAP_DOM_ASIS
#define SOAP_DOM_ASIS
soap_mode DOM output flag value to disable reformatting of the DOM node tree in XML,...
Definition stdsoap2.h:2204
soap::recvfd
int recvfd
The file descriptor to read data from when no socket communications are set (soap::socket == #SOAP_IN...
Definition stdsoap2.h:3171
soap::sendfd
int sendfd
The file descriptor to write data to when no socket communications are set (soap::socket == #SOAP_INV...
Definition stdsoap2.h:3190
soap::dom
*DOM tree received struct soap_dom_element * dom
Definition stdsoap2.h:4304

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.

## ◆ SOAP_DOM_NODE

#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
SOAP_DOM_NODE
#define SOAP_DOM_NODE
soap_mode DOM input flag value to always attempt to deserialize embedded serializable C/C++ data stru...
Definition stdsoap2.h:2228

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.

## ◆ SOAP_DOM_TREE

#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;
SOAP_DOM_TREE
#define SOAP_DOM_TREE
soap_mode DOM input flag value to ignore id and xsi:type XML attributes and disables deserialization ...
Definition stdsoap2.h:2249

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.

## ◆ SOAP_ENC

#define SOAP_ENC 0x00000FFF

soap_mode ENC flags mask (for internal use only)

## ◆ SOAP_ENC_DIME

#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
soap_strdup
*Copy a string to managed memory char * soap_strdup(struct soap *soap, const char *string) * @returns copy of string or NULL when the specified string is NULL or on failure to allocate(out of memory)
soap_malloc
*Allocate a block of heap memory managed by the specified ::soap context void * soap_malloc(struct soap *soap, size_t len) * @returns pointer to the allocated block of memory or NULL on failure to allocate(out of memory)
soap_dime_option
char * soap_dime_option(struct soap *soap, unsigned short optype, const char *option)
Creates a DIME option.
soap_rand_uuid
const char * soap_rand_uuid(struct soap *soap, const char *prefix)
Returns a randomized unique UUID string.
_xop__Include
XOP include structure with attachment data.
Definition stdsoap2.h:10080
_xop__Include::__ptr
unsigned char * __ptr
pointer to binary data
Definition stdsoap2.h:10081
#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
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.

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.

## ◆ SOAP_ENC_LATIN

#define SOAP_ENC_LATIN 0x00000020

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

## ◆ SOAP_ENC_MIME

#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
SOAP_ENC_MIME
#define SOAP_ENC_MIME
soap_mode ENC output flag value to enable MIME attachments in messages to be sent,...
Definition stdsoap2.h:1843
#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);
soap_set_mime_attachment
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.
SOAP_MIME_BINARY
@ SOAP_MIME_BINARY
binary raw data content
Definition stdsoap2.h:10424

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
soap_set_omode
*Set output ::soap_mode flags of the given ::soap context void soap_set_omode(struct soap *soap, soap_mode output_mode)

To disable:

soap_clr_omode(soap, SOAP_ENC_MIME);
soap_clr_omode
*Clear output ::soap_mode flags of the given ::soap context void soap_clr_omode(struct soap *soap, soap_mode output_mode)

See also
  #SOAP_ENC_DIME, #SOAP_ENC_MTOM, MIME attachments.

## ◆ SOAP_ENC_MTOM

#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
SOAP_ENC_MTOM
#define SOAP_ENC_MTOM
soap_mode ENC output flag value to enable MTOM XOP attachments in messages to be sent,...
Definition stdsoap2.h:1892
#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.

## ◆ SOAP_ENC_PLAIN

#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
SOAP_ENC_PLAIN
#define SOAP_ENC_PLAIN
soap_mode ENC input/output flag value to omit the HTTP headers from messages sent and disable detecti...
Definition stdsoap2.h:1750

## ◆ SOAP_ENC_SSL

#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)

## ◆ SOAP_ENC_XML

#define SOAP_ENC_XML

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

## ◆ SOAP_ENC_ZLIB

#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
SOAP_ENC_ZLIB
#define SOAP_ENC_ZLIB
soap_mode ENC output flag value to compress messages sent, requires zlib enabled with compile-time fl...
Definition stdsoap2.h:1904

## ◆ SOAP_IO

#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
SOAP_IO
#define SOAP_IO
soap_mode IO flags mask to check for #SOAP_IO_FLUSH, #SOAP_IO_BUFFER, #SOAP_IO_STORE,...
Definition stdsoap2.h:1636
SOAP_IO_CHUNK
#define SOAP_IO_CHUNK
soap_mode IO output flag value to send HTTP chunked messages, buffers the message in packets of size ...
Definition stdsoap2.h:1672
soap::omode
soap_mode omode
The soap context output soap_mode flags that are set at context initialization and set or cleared wit...
Definition stdsoap2.h:2960

## ◆ SOAP_IO_BUFFER

#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

## ◆ 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

## ◆ SOAP_IO_FLUSH

#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

## ◆ SOAP_IO_KEEPALIVE

#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
SOAP_IO_KEEPALIVE
#define SOAP_IO_KEEPALIVE
soap_mode IO input and output flag value to keep the socket connection alive for #SOAP_MAXKEEPALIVE m...
Definition stdsoap2.h:1732
soap::max_keep_alive
int max_keep_alive
User-definable maximum number of keep-alive message exchanges per connection (the value is #SOAP_MAXK...
Definition stdsoap2.h:3026
#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
soap_set_mode
*Set input and output ::soap_mode flags of the given ::soap context void soap_set_mode(struct soap *soap, soap_mode input_and_output_mode)
soap_clr_mode
*Clear input and output ::soap_mode flags of the given ::soap context void soap_clr_mode(struct soap *soap, soap_mode input_and_output_mode)
soap_print_fault
void soap_print_fault(struct soap *soap, FILE *fd)
Print error message on the specified output.
soap::endpoint
char endpoint[SOAP_TAGLEN]
The endpoint URL as received on the server side.
Definition stdsoap2.h:4143

See also
  soap::keep_alive, soap::max_keep_alive, #SOAP_MAXKEEPALIVE.

## ◆ SOAP_IO_LENGTH

#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.

## ◆ SOAP_IO_STORE

#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
SOAP_IO_STORE
#define SOAP_IO_STORE
soap_mode IO output flag value to store messages temporarily before transmission, e....
Definition stdsoap2.h:1658

## ◆ SOAP_IO_UDP

#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
SOAP_IO_UDP
#define SOAP_IO_UDP
soap_mode IO input/output flag value to use UDP datagrams, message size is limited to UDP packet size
Definition stdsoap2.h:1686

See also
  SOAP/XML over UDP.

## ◆ SOAP_MIME_POSTCHECK

#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.

## ◆ SOAP_SEC_WSUID

#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)

## ◆ SOAP_XML_CANONICAL

#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
SOAP_XML_CANONICAL
#define SOAP_XML_CANONICAL
soap_mode XML output flag value to send XML messages in exclusive canonical format as per W3C XML C14...
Definition stdsoap2.h:2083
soap::c14ninclude
const char * c14ninclude
User-definable string to control the XML namespace prefixes that are subject to XML canonicalization ...
Definition stdsoap2.h:3033

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.

## ◆ 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
SOAP_XML_CANONICAL_NA
#define SOAP_XML_CANONICAL_NA
soap_mode XML output flag value to send XML messages in exclusive canonical format as per W3C XML C14...
Definition stdsoap2.h:2100

See also
  #SOAP_XML_CANONICAL.

## ◆ SOAP_XML_DEFAULTNS

#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="..."
SOAP_XML_DEFAULTNS
#define SOAP_XML_DEFAULTNS
soap_mode XML output flag value to send XML messages with XML default namespaces for elements instead...
Definition stdsoap2.h:1990

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.

## ◆ SOAP_XML_DOM

#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))
}
SOAP_XML_DOM
#define SOAP_XML_DOM
soap_mode XML input/output flag value to enable DOM node tree construction of the XML received and se...
Definition stdsoap2.h:2179

## ◆ SOAP_XML_GRAPH

#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 intended to accurately (de)serialize C/C++ data structures, including cyclic data references e.g. through the use of pointers in the data structures. This (de)serialization mode is normally active with SOAP 1.1/1.2 serialization to preserve and process the XML data binding to C/C++, including multi-referenced objects in XML. 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
SOAP_XML_GRAPH
#define SOAP_XML_GRAPH
soap_mode XML input/output flag value to serialize C/C++ (cyclic) data structures in XML with id-ref ...
Definition stdsoap2.h:2137

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

See also
  #SOAP_XML_TREE.

## ◆ SOAP_XML_IGNORENS

#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
SOAP_XML_IGNORENS
#define SOAP_XML_IGNORENS
soap_mode XML input flag value to ignore XML namespaces in messages received
Definition stdsoap2.h:1949

## ◆ SOAP_XML_INDENT

#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
SOAP_XML_INDENT
#define SOAP_XML_INDENT
soap_mode XML output flag value to enable XML (and JSON) message indentation in messages sent
Definition stdsoap2.h:1937

## ◆ SOAP_XML_NIL

#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"
SOAP_XML_NIL
#define SOAP_XML_NIL
soap_mode XML output flag value to serialize C/C++ NULL pointers in XML as elements with attribute xs...
Definition stdsoap2.h:2149

## ◆ SOAP_XML_NOTYPE

#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
SOAP_XML_NOTYPE
#define SOAP_XML_NOTYPE
soap_mode XML output flag value to serialize C/C++ data structures in XML without xsi:type attributes...
Definition stdsoap2.h:2161

## ◆ SOAP_XML_STRICT

#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
SOAP_XML_STRICT
#define SOAP_XML_STRICT
soap_mode XML input flag value to enable strict XML validation of messages received
Definition stdsoap2.h:1925

See also
  #WITH_REPLACE_ILLEGAL_UTF8, #SOAP_UNKNOWN_UNICODE_CHAR.

## ◆ SOAP_XML_TREE

#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 and ignores these attributes during deserialization.

For data serialization to XML, the serializer duplicates co-referenced data in the XML output and automatically breaks data structure cycles to prevent infinite serialization loops. For deserialization from XML, the deserializer 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
SOAP_XML_TREE
#define SOAP_XML_TREE
soap_mode XML input/output flag value to serialize C/C++ data structures as XML trees without id-href...
Definition stdsoap2.h:2118

Note
  This mode flag is always active when the engine source code is compiled with #WITH_NOIDREF.

See also
  #SOAP_XML_GRAPH, #WITH_NOIDREF.

## Typedef Documentation

## ◆ soap_mode

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