Genivia - WITH_MACRO compile-time flags

|  | Home | Documentation | WITH_MACRO compile-time flags updated Mon Apr 22 2024 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Macros
WITH_MACRO compile-time flags

This module defines the `WITH_MACRO` compile-time flags to configure the engine build. More...

## Macros
#define | SOAPDEFS_H
| When this macro is defined at compile time (undefined by default) then the header file specified by this macro is included in the build via stdsoap2.h. More...
#define | WITH_SOAPDEFS_H
| When this macro is defined at compile time (undefined by default), a user-supplied file named soapdefs.h is included in the build, i.e. soapdefs.h can be used to configure the build by defining compile-time macros and flags. More...
#define | WITH_COMPAT
| When this macro is defined at compile time (undefined by default), removes dependency on C++ `std::string` and `std::iostream` libraries. More...
#define | WITH_LEAN
| When this macro is defined at compile time (undefined by default), memory footprint is significantly reduced by removing non-essential features from the engine and from the generated code. More...
#define | WITH_LEANER
| When this macro is defined at compile time (undefined by default), memory footprint is further reduced from `WITH_LEAN` by removing non-essential features from the engine and from the generated code. More...
#define | WITH_FAST
| When this macro is defined at compile time uses faster memory allocation at a cost of larger memory blocks allocated (defined by default except with `WITH_LEAN` and `WITH_LEANER)` More...
#define | WITH_COOKIES
| When this macro is defined at compile time (undefined by default), HTTP cookie support is enabled in the engine. More...
#define | WITH_INSECURE_COOKIES
| When this macro is defined at compile time (undefined by default), HTTP cookie support is enabled (as `WITH_COOKIES`) but allows cookies with their Secure flag set to be sent over insecure channels. More...
#define | WITH_IPV6
| When this macro is defined at compile time (undefined by default), IPv6 support is enabled and both IPv4 and IPv6 connections are supported by the engine. More...
#define | WITH_IPV6_V6ONLY
| When this macro is defined at compile time (undefined by default), IPv6-only is enabled for port binding at the server side by the engine to ensure that a socket will only use IPv6 without mapping IPv4 to IPv6. More...
#define | WITH_OPENSSL
| When this macro is defined at compile time (undefined by default), enables activation and linkage with OpenSSL for HTTPS and WS-Security (this macro should also be defined when using plugins that rely on OpenSSL) More...
#define | WITH_GNUTLS
| When this macro is defined at compile time (undefined by default), enables activation and linkage the GNUTLS library to enable HTTPS in the engine. More...
#define | WITH_WOLFSSL
| When this macro is defined at compile time (undefined by default), enables activation and linkage of the WolfSSL library to enable HTTPS in the engine. More...
#define | WITH_GZIP
| When this macro is defined at compile time (undefined by default), enables linkage with the zlib library for HTTP message compression (using compress and gzip methods) when the `SOAP_ENC_ZLIB` mode flag is enabled at runtime. More...
#define | WITH_ZLIB
| When this macro is defined at compile time (undefined by default), enables linking the zlib library for HTTP message compression when the `SOAP_ENC_ZLIB` mode flag is enabled at runtime. More...
#define | WITH_NTLM
| When this macro is defined at compile time (undefined by default), enables linkage with the ntlm library for HTTP NTLM authentication. More...
#define | WITH_C_LOCALE
| When this macro is defined at compile time (defined by default for most platforms), the C locale is enabled in the engine, opposite of `WITH_NO_C_LOCALE` More...
#define | WITH_NO_C_LOCALE
| When this macro is defined at compile time (undefined by default), the use of the C locale is disabled in the engine, the opposite of `WITH_C_LOCALE` More...
#define | WITH_INCLUDE_XLOCALE_H
| When this macro is defined at compile time (defined by default for most platforms), include xlocale.h to define `locale_t` and the `_l` locale-specific functions. More...
#define | WITH_DOM
| When this macro is defined at compile time (undefined by default), enables WS-Security signature verification and XML re-canonicalization, i.e. this macro must be defined when using the gSOAP WSSE plugin for WS-Security. More...
#define | WITH_REPLACE_ILLEGAL_UTF8
| When this macro is defined at compile time (undefined by default), replaces UTF-8 content that is outside the Unicode range with the value of `SOAP_UNKNOWN_UNICODE_CHAR` (Unicode FFFD) to indicate illegal UTF-8, set `SOAP_UNKNOWN_UNICODE_CHAR` to another integer code if desired (the value is 0xFFFD by default) More...
#define | WITH_FASTCGI
| When this macro is defined at compile time (undefined by default), enables and configures the engine and generated code to use FastCGI at the server side. More...
#define | WITH_NOIO
| When this macro is defined at compile time (undefined by default), removes all IO and socket library calls to replace these with user-supplied callback functions, see the IO callbacks in the user guide. More...
#define | WITH_NOIDREF
| When this macro is defined at compile time (undefined by default), permanently disables XML ID (`id` attribute) and REF (`href` or `ref` attribute) processing rules associated with SOAP 1.1 and SOAP 1.2 "multi-reference" data to serialize object graphs, this is a more aggressive optimization option than the runtime `SOAP_XML_TREE` flag. More...
#define | WITH_NOHTTP
| When this macro is defined at compile time (undefined by default), permanently removes the HTTP stack to reduce code size. More...
#define | WITH_NOZONE
| When this macro is defined at compile time (undefined by default), removes and ignores the timezone in `xsd:dateTime` values. More...
#define | WITH_NOEMPTYNAMESPACES
| When this macro is defined at compile time, default empty namespaces are not required to parse XML and are disabled from XML messages when the `SOAP_XML_DEFAULTNS` mode flag is used. More...
#define | WITH_NOEMPTYSTRUCT
#define | WITH_NOGLOBAL
| When this macro is defined at compile time (undefined by default), omits SOAP Header and Fault serialization code, this flag prevents duplicate definitions in the source code generated by soapcpp2. More...
#define | WITH_NONAMESPACES
| When this macro is defined at compile time (undefined by default), removes dependence on the global `namespaces` table, rather users must set the XML namespaces explicitly by calling `soap_set_namespaces` More...
#define | WITH_CDATA
| When this macro is defined at compile time (undefined by default), retains the parsed CDATA sections in literal XML strings. More...
#define | WITH_PURE_VIRTUAL
| When this macro is defined at compile time (undefined by default), makes C++ service class operation methods and the copy method pure virtual by defining `SOAP_PURE_VIRTUAL` = 0. More...
#define | WITH_DEFAULT_VIRTUAL
| When this macro is defined at compile time (undefined by default), enables C++ base service classes with default virtual methods returning fault `SOAP_NO_METHOD` More...
#define | WITH_CASEINSENSITIVETAGS
| When this macro is defined at compile time (undefined by default), enables case insensitive XML tag name parsing and validation. More...
#define | WITH_SOCKET_CLOSE_ON_EXIT
| When this macro is defined at compile time (undefined by default), prevents a server port from staying in listening mode after exit by internally setting `fcntl(sock, F_SETFD, FD_CLOEXEC)` More...
#define | WITH_TCPFIN
| When this macro is defined at compile time (undefined by default), the engine transmits TCP FIN using `shutdown(sock, SHUT_WR)` after all sends are completed and just before the socket closes. More...
#define | WITH_SSL_FULL_SHUTDOWN
| When this macro is defined at compile time (undefined by default), the engine calls `SSL_shutdown(ssl)` twice, the second after `close_notify` (with a 5 second timeout), before closing the socket (`WITH_LEAN` n/a: calls `SSL_shutdown(ssl)` a second time without any timeout) More...
#define | WITH_SELF_PIPE
| When this macro is defined at compile time (undefined by default), the engine is configured to enable `soap_close_connection` using a "self-pipe". More...
#define | WITH_CRTOLF
| When this macro is defined at compile time (undefined by default), the engine is configured to replace CRLF (carriage return `#xD` followed by line feed `#xA`) by LF and replace single CR by LF. More...

## Detailed Description

This module defines the `WITH_MACRO` compile-time flags to configure the engine build.

This module defines the following compile-time flags to configure the engine build:

- `SOAPDEFS_H`
- `WITH_SOAPDEFS_H`
- `WITH_COMPAT`
- `WITH_LEAN`
- `WITH_LEANER`
- `WITH_FAST`
- `WITH_COOKIES`
- `WITH_INSECURE_COOKIES`
- `WITH_IPV6`
- `WITH_IPV6_V6ONLY`
- `WITH_OPENSSL`
- `WITH_GNUTLS`
- `WITH_WOLFSSL`
- `WITH_GZIP`
- `WITH_ZLIB`
- `WITH_NTLM`
- `WITH_C_LOCALE`
- `WITH_NO_C_LOCALE`
- `WITH_INCLUDE_XLOCALE_H`
- `WITH_DOM`
- `WITH_REPLACE_ILLEGAL_UTF8`
- `WITH_FASTCGI`
- `WITH_NOIO`
- `WITH_NOIDREF`
- `WITH_NOHTTP`
- `WITH_NOZONE`
- `WITH_NOEMPTYNAMESPACES`
- `WITH_NOEMPTYSTRUCT`
- `WITH_NOGLOBAL`
- `WITH_NONAMESPACES`
- `WITH_CDATA`
- `WITH_PURE_VIRTUAL`
- `WITH_DEFAULT_VIRTUAL`
- `WITH_CASEINSENSITIVETAGS`
- `WITH_SOCKET_CLOSE_ON_EXIT`
- `WITH_TCPFIN`
- `WITH_SSL_FULL_SHUTDOWN`
- `WITH_SELF_PIPE`
- `WITH_CRTOLF`

## Macro Definition Documentation

#define SOAPDEFS_H

When this macro is defined at compile time (undefined by default) then the header file specified by this macro is included in the build via stdsoap2.h.

This macro specifies the name of a header file to include and can be used to configure the engine build by defining WITH_MACRO compile-time flags and SOAP_MACRO compile-time values.

Example:

      cat mydefs.h
      #define WITH_OPENSSL
      #define WITH_DOM
      c++ -D SOAPDEFS_H=mydefs.h -o client stdsoap2.cpp dom.cpp soapC.cpp soapClient.cpp client.cpp -lcrypto -lssl

See also
  `WITH_SOAPDEFS_H`.

#define WITH_C_LOCALE

When this macro is defined at compile time (defined by default for most platforms), the C locale is enabled in the engine, opposite of `WITH_NO_C_LOCALE`

This macro prevents floating point values from getting garbled by the standard locale-dependent `strtod` and `sprintf` functions used by the engine, for example when the current locale of the machine redefines the decimal point.

#define WITH_CASEINSENSITIVETAGS

When this macro is defined at compile time (undefined by default), enables case insensitive XML tag name parsing and validation.

XML is case sensitive, whereas HTML is case insensitive. XML parsing is always case insensitive unless overruled by thie macro.

Example:

      c++ -D WITH_CASEINSENSITIVETAGS -c stdsoap2.cpp

#define WITH_CDATA

When this macro is defined at compile time (undefined by default), retains the parsed CDATA sections in literal XML strings.

Literal XML strings are built-in `_XML` types (a typedef of `char*`) in the .h file for soapcpp2, or a user-defined `typedef std::string XML` to define a `XML` literal string. Literal XML strings contain XML, but CDATA sections are stripped by the XML parser unless this macro is enabled.

Example:

      soapcpp2 -C myservice.h
      c++ -D WITH_CDATA -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp

  // example myservice.h file for soapcpp2
  //gsoap ns service name: example
  //gsoap ns service namespace: urn:example
  int ns__webmethod(_XML string, _XML *response); // _XML is a literal XML string (a char* type)
  // example client.cpp file
  #include "soapH.h"
  #include "example.nsmap"
  struct soap *soap = soap_new1(SOAP_XML_INDENT);
  if (soap_call_ns__webmethod(soap, endpoint, NULL, "<doc title=\"Example\">Some text</doc>", &r))
  soap_print_fault(soap, stderr);
  else
  printf("XML = %s\n", response);
  soap_destroy(soap);
  soap_end(soap);
  soap_free(soap);
  Request and response messages:
  1 <?xml version="1.0" encoding="UTF-8"?>
  2 <SOAP-ENV:Envelope
  3 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  4 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  5 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  6 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  7 xmlns:ns="urn:example">
  8 <SOAP-ENV:Body>
  9 <ns:webmethod>
  10 <doc title="Example">Some text</doc>
  11 </ns:webmethod>
  12 </SOAP-ENV:Body>
  13 </SOAP-ENV:Envelope>
  1 <?xml version="1.0" encoding="UTF-8"?>
  2 <SOAP-ENV:Envelope
  3 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  4 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  5 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  6 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  7 xmlns:ns="urn:example">
  8 <SOAP-ENV:Body>
  9 <ns:webmethodResponse>
  10 <![CDATA[<doc title="Example">Some text</doc>]]>
  11 </ns:webmethodResponse>
  12 </SOAP-ENV:Body>
  13 </SOAP-ENV:Envelope>
  Output with `WITH_CDATA`:

      XML = <![CDATA[<doc title="Example">Some text</doc>]]>

  Output without `WITH_CDATA`:

      XML = <doc title="Example">Some text</doc>

#define WITH_COMPAT

When this macro is defined at compile time (undefined by default), removes dependency on C++ `std::string` and `std::iostream` libraries.

Example:

      c++ -D WITH_COMPAT -c stdsoap2.cpp

#define WITH_COOKIES

When this macro is defined at compile time (undefined by default), HTTP cookie support is enabled in the engine.

Use the following functions to set and get HTTP cookie values:

- `soap_set_cookie`
- `soap_set_cookie_expire`
- `soap_set_cookie_secure`
- `soap_set_cookie_session`
- `soap_clr_cookie`
- `soap_clr_cookie_session`
- `soap_cookie`
- `soap_cookie_value`
- `soap_cookie_expire`
- `soap_getenv_cookies`
- `soap_free_cookies`

Client-side HTTP cookie handling is automatic. The `WITH_COOKIES` flag is useless without server-side session management and control. Cookies may require a fair amount of processing overhead and are not needed to implement stateful services, which is typically performed with session IDs in XML/JSON messages or via the URL.

Examples:

      c++ -D WITH_COOKIES -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_COOKIES -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

See also
  The HTTP Server Session Management plugin documentation to use the HTTP session plugin to store a database of sessions to keep track of client data across multiple requests.

#define WITH_CRTOLF

When this macro is defined at compile time (undefined by default), the engine is configured to replace CRLF (carriage return `#xD` followed by line feed `#xA`) by LF and replace single CR by LF.

This macro affects C/C++ string serialization to XML. If `char*`, `wchar_t*`, `std::string`, or `std::wstring` values assigned by an application contain CR, then this macro effectively removes all CR in the normalized XML output by replacing CRLF with LF and each plain CR with a LF. This macro does not affect parsed and deserialized strings and does not affect `_XML` literal string serialization to XML i.e. strings containing raw XML.

The XML 1.1. standard recommends replacing CRLF by LF and each single CR by LF in XML character data. This flag is useful when C/C++ string values to serialize to XML may contain CR characters.

Example:

      c++ -D WITH_CRTOLF -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp

  // compiled with compile-time flag -D WITH_CRTOLF
  #include "soapH.h"
  struct soap *soap = soap_new();
  struct ns__webmethodResponse result;
  ... //
  if (soap_call_ns__webmethod(soap, endpoint, NULL, "Message\r\n", &result))
  soap_print_fault(soap, stderr);
  else
  ... // success
  In the example shown above, the message `Message\n` will be sent.

#define WITH_DEFAULT_VIRTUAL

When this macro is defined at compile time (undefined by default), enables C++ base service classes with default virtual methods returning fault `SOAP_NO_METHOD`

Use `WITH_DEFAULT_VIRTUAL` to make C++ service class operation methods return `SOAP_NO_METHOD` for rapid Web API prototyping and development.

Note
  Requires `soapcpp2 -j` option `-j` or option `-i` to generate C++ service classes.

Example:

      soapcpp2 -j myservice.h
      c++ -D WITH_DEFAULT_VIRTUAL -o server stdsoap2.cpp soapC.cpp soapMyService.cpp server.cpp

  // example myservice.h file for soapcpp2
  //gsoap ns service name: example
  //gsoap ns service namespace: urn:example
  struct ns__webmethodResponse {
  char *string;
  };
  int ns__webmethod(char *string, struct ns__webmethodResponse *response);
  // example server.cpp file
  #include "soapexampleService.h"
  #include "example.nsmap"
  class MyService : public exampleService {
  public:
  virtual int webmethod(char *string, struct ns__webmethodResponse *response)
  {
  response->string = string;
  return SOAP_OK;
  }
  // note: other methods (if any) will return SOAP_NO_METHOD
  };
  int main()
  {
  return MyService().run(PORTNUM);
  }

#define WITH_DOM

When this macro is defined at compile time (undefined by default), enables WS-Security signature verification and XML re-canonicalization, i.e. this macro must be defined when using the gSOAP WSSE plugin for WS-Security.

To enable DOM parsing use `SOAP_XML_DOM`, for 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
}

Examples:

      c++ -D WITH_OPENSSL -D WITH_DOM -o client stdsoap2.cpp dom.cpp soapC.cpp soapClient.cpp client.cpp plugin/smdevp.c plugin/mecevp.c plugin/wsseapi.c plugin/threads.c -lcrypto -lssl
      c++ -D WITH_OPENSSL -D WITH_DOM -o server stdsoap2.cpp dom.cpp soapC.cpp soapServer.cpp server.cpp plugin/smdevp.c plugin/mecevp.c plugin/wsseapi.c plugin/threads.c -lcrypto -lssl

See also
  `SOAP_XML_DOM` and the gSOAP XML DOM API documentation.

#define WITH_FAST

When this macro is defined at compile time uses faster memory allocation at a cost of larger memory blocks allocated (defined by default except with `WITH_LEAN` and `WITH_LEANER)`

Examples:

      c++ -D WITH_FAST -D WITH_LEANER -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_FAST -D WITH_LEAN -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

#define WITH_FASTCGI

When this macro is defined at compile time (undefined by default), enables and configures the engine and generated code to use FastCGI at the server side.

Call `soap_serve` (or the C++ service class `serve` method) to serve CGI and FastCGI requests (only FastCGI requires `WITH_FASTCGI` but CGI works without this configuration).

Example:

      soapcpp2 myservice.h
      c++ -D WITH_FASTCGI -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

  // example server.cpp
  #include "soapH.h"
  int main()
  {
  struct soap *soap = soap_new();
  soap_serve(soap);
  soap_destroy(soap);
  soap_end(soap);
  soap_free(soap);
  }
  ... // web method implementations

#define WITH_GNUTLS

When this macro is defined at compile time (undefined by default), enables activation and linkage the GNUTLS library to enable HTTPS in the engine.

Use the following functions to configure SSL/TLS connections and to accept SSL/TLS connections:

- `soap_ssl_init`
- `soap_ssl_noinit`
- `soap_ssl_client_context`
- `soap_ssl_server_context`
- `soap_ssl_crl`
- `soap_ssl_accept`

Examples:

      c++ -D WITH_GNUTLS -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp -lgnutls
      c++ -D WITH_GNUTLS -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp -lgnutls

Link with libgnutls and optionally libgcrypt and libgpg-error.

#define WITH_GZIP

When this macro is defined at compile time (undefined by default), enables linkage with the zlib library for HTTP message compression (using compress and gzip methods) when the `SOAP_ENC_ZLIB` mode flag is enabled at runtime.

To enable compression with the gzip method and decompression with the compress and gzip methods, use `SOAP_ENC_ZLIB`:

#include "soapH.h"
struct soap *soap = soap_new1(SOAP_ENC_ZLIB);

Examples:

      c++ -D WITH_GZIP -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp -lz
      c++ -D WITH_GZIP -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp -lz

See also
  `WITH_ZLIB` to only enable compress but not gzip compression.

#define WITH_INCLUDE_XLOCALE_H

When this macro is defined at compile time (defined by default for most platforms), include xlocale.h to define `locale_t` and the `_l` locale-specific functions.

#define WITH_INSECURE_COOKIES

When this macro is defined at compile time (undefined by default), HTTP cookie support is enabled (as `WITH_COOKIES`) but allows cookies with their Secure flag set to be sent over insecure channels.

Use the following functions to set and get HTTP cookie values:

- `soap_set_cookie`
- `soap_set_cookie_expire`
- `soap_set_cookie_secure`
- `soap_set_cookie_session`
- `soap_clr_cookie`
- `soap_clr_cookie_session`
- `soap_cookie`
- `soap_cookie_value`
- `soap_cookie_expire`
- `soap_getenv_cookies`
- `soap_free_cookies`

Examples:

      c++ -D WITH_INSECURE_COOKIES -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_INSECURE_COOKIES -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

See also
  The HTTP Server Session Management plugin documentation to use the HTTP session plugin to store a database of sessions to keep track of client data across multiple requests.

#define WITH_IPV6

When this macro is defined at compile time (undefined by default), IPv6 support is enabled and both IPv4 and IPv6 connections are supported by the engine.

Use `soap::bind_inet6` and `soap::bind_v6only` at runtime to configure port bindings at the server side:

#include "soapH.h"
struct soap *soap = soap_new();
soap->bind_inet6 = 1; // to use AF_INET6 instead of PF_UNSPEC
soap->bind_v6only = 1; // to setsockopt IPPROTO_IPV6 IPV6_V6ONLY
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
...

Example:

      c++ -D WITH_IPV6 -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

#define WITH_IPV6_V6ONLY

When this macro is defined at compile time (undefined by default), IPv6-only is enabled for port binding at the server side by the engine to ensure that a socket will only use IPv6 without mapping IPv4 to IPv6.

Alternatively, compile with `WITH_IPV6` and set `soap::bind_v6only` at runtime to do the same as `WITH_IPV6_V6ONLY`:

#include "soapH.h"
struct soap *soap = soap_new();
soap->bind_inet6 = 1; // to use AF_INET6 instead of PF_UNSPEC
soap->bind_v6only = 1; // to setsockopt IPPROTO_IPV6 IPV6_V6ONLY
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
...

Example:

      c++ -D WITH_IPV6_ONLY -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

#define WITH_LEAN

When this macro is defined at compile time (undefined by default), memory footprint is significantly reduced by removing non-essential features from the engine and from the generated code.

Warning
  `WITH_LEAN` disables the following features:
  - UDP `SOAP_IO_UDP`
  - HTTP keep-alive `SOAP_IO_KEEPALIVE`
  - HTTP authentication with `soap::userid` and `soap::passwd`
  - HTTP chunked transfers `SOAP_IO_CHUNK` except HTTP chunked input
  - HTTP compression `SOAP_ENC_ZLIB` except HTTP compressed input
  - canonical XML `SOAP_XML_CANONICAL`, `SOAP_XML_CANONICAL_NA`
  - timeouts `soap::connect_timeout`, `soap::send_timeout`, `soap::recv_timeout` and `soap::transfer_timeout`
  - socket flags `soap::socket_flags`, `soap::connect_flags`, `soap::bind_flags`, `soap::accept_flags`
  - `time_t` serialization as `xsd__dateTime` (use a string to store the date and time instead)
  - `soap_poll` always returns `SOAP_OK`
  When this macro is define at the compiler's command line or in an IDE or by specifying `SOAPDEFS_H`, then all source code files of an application's project must be recompiled. Otherwise, `soap` context corruption errors may occur in the non-recompiled parts of the application, because the size of the `soap` context has changed.

Examples:

      c++ -D WITH_LEAN -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_LEAN -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

#define WITH_LEANER

When this macro is defined at compile time (undefined by default), memory footprint is further reduced from `WITH_LEAN` by removing non-essential features from the engine and from the generated code.

Warning
  `WITH_LEANER` disables the following features:
  - UDP `SOAP_IO_UDP`
  - HTTP keep-alive `SOAP_IO_KEEPALIVE`
  - HTTP authentication with `soap::userid` and `soap::passwd`
  - HTTP chunked transfers `SOAP_IO_CHUNK` except HTTP chunked input
  - HTTP compression `SOAP_ENC_ZLIB` except HTTP compressed input
  - canonical XML `SOAP_XML_CANONICAL`, `SOAP_XML_CANONICAL_NA`
  - timeouts `soap::connect_timeout`, `soap::send_timeout`, `soap::recv_timeout` and `soap::transfer_timeout`
  - socket flags `soap::socket_flags`, `soap::connect_flags`, `soap::bind_flags`, `soap::accept_flags`
  - `time_t` serialization as `xsd__dateTime` (use a string to store the date and time instead)
  - `soap_poll` always returns `SOAP_OK`
  - wide string serializers
  - DIME and MIME/MTOM attachments
  - XML DOM operations with the DOM API
  When this macro is define at the compiler's command line or in an IDE or by specifying `SOAPDEFS_H`, then all source code files of an application's project must be recompiled. Otherwise, `soap` context corruption errors may occur in the non-recompiled parts of the application, because the size of the `soap` context has changed.

Examples:

      c++ -D WITH_LEANER -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_LEANER -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

#define WITH_NO_C_LOCALE

When this macro is defined at compile time (undefined by default), the use of the C locale is disabled in the engine, the opposite of `WITH_C_LOCALE`

Defining this macro improves portability of the engine's source code on older platforms that do not have working versions of locale.h and xlocale.h.

Warning
  When the current locale of the machine redefines the decimal point, floating point values may be rejected by the XML validator and may be garbled in XML and JSON output due to the standard locale-dependent `strtod` and `sprintf` functions.

Example:

      c++ -D WITH_NO_C_LOCALE -c stdsoap2.cpp

#define WITH_NOEMPTYNAMESPACES

When this macro is defined at compile time, default empty namespaces are not required to parse XML and are disabled from XML messages when the `SOAP_XML_DEFAULTNS` mode flag is used.

This macro is intended for backward compatibility with old XML parsers and old gSOAP versions that do not support `xmlns=""` empty default namespaces. When used with the runtime `SOAP_XML_DEFAULTNS` mode flag, produces XML that lacks `xmlns=""` which should only be used for special cases and is not recommended in general.

Warning
  This macro should only be used to resolve issues with older tools that do not support `xmlns=""` in XML messages or when XML messages should be parsed and validated that do not include `xmlns=""` that are normally expected in valid XML.

#define WITH_NOEMPTYSTRUCT

When this macro is defined at compile time (undefined by default), omits SOAP Header and Fault serialization code, this flag prevents duplicate definitions in the source code generated by soapcpp2 When this macro is defined at compile time (defined for C but undefined for C++), the generated code by the soapcpp2 tool inserts a dummy member in empty structs to allow compilation to succeed with compilers that reject empty structs and unions

#define WITH_NOGLOBAL

When this macro is defined at compile time (undefined by default), omits SOAP Header and Fault serialization code, this flag prevents duplicate definitions in the source code generated by soapcpp2.

This macro is used in the generated files when `soapcpp2 -pname` option `-pname` is used.

#define WITH_NOHTTP

When this macro is defined at compile time (undefined by default), permanently removes the HTTP stack to reduce code size.

Example:

      c++ -D WITH_NOHTTP -o xmlapp stdsoap2.cpp soapC.cpp xmlapp.cpp

#define WITH_NOIDREF

When this macro is defined at compile time (undefined by default), permanently disables XML ID (`id` attribute) and REF (`href` or `ref` attribute) processing rules associated with SOAP 1.1 and SOAP 1.2 "multi-reference" data to serialize object graphs, this is a more aggressive optimization option than the runtime `SOAP_XML_TREE` flag.

Alternatively, set `SOAP_XML_TREE` at runtime:

#include "soapH.h"
struct soap *soap = soap_new1(SOAP_XML_TREE);

Examples:

      c++ -D WITH_NOIDREF -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_NOIDREF -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

See also
  `SOAP_XML_TREE`, `SOAP_XML_GRAPH`.

#define WITH_NOIO

When this macro is defined at compile time (undefined by default), removes all IO and socket library calls to replace these with user-supplied callback functions, see the IO callbacks in the user guide.

The following IO and socket-related functions should be defined by callbacks implemented by the user as follows:

#include "soapH.h"
int my_accept(struct soap *soap, SOAP_SOCKET sock, struct sockaddr *addr, int *len) { ... }
int my_connect(struct soap *soap, const char *endpoint, const char *host, int port) { ... }
int my_disconnect(struct soap *soap) { ... }
int my_closesocket(struct soap *soap, SOAP_SOCKET sock) { ... }
int my_shutdownsocket(struct soap *soap, SOAP_SOCKET sock, int how) { ... }
int my_send(struct soap *soap, const char *data, size_t len) { ... }
size_t my_recv(struct soap *soap, char *buf, size_t len) { ... }
int my_poll(struct soap *soap) { ... }
struct soap *soap = soap_new();
soap->faccept = my_accept;
soap->fopen = my_connect;
soap->fclose = my_disconnect;
soap->fclosesocket = my_close;
soap->fshutdownsocket = my_shutdown;
soap->fsend = my_send;
soap->frecv = my_recv;
soap->fpoll = my_poll;

The socket-related callbacks can be omitted when only basic IO operations are needed to read/write XML with the `soap::frecv` and `soap::fsend` callbacks.

Warning
  When this macro is define at the compiler's command line or in an IDE or by specifying `SOAPDEFS_H`, then all source code files of an application's project must be recompiled. Otherwise, `soap` context corruption errors may occur in the non-recompiled parts of the application, because the size of the `soap` context has changed.

Examples:

      c++ -D WITH_NOIO -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_NOIO -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

See also
  `soap::faccept`, `soap::fopen`, `soap::fclose`, `soap::fclosesocket`, `soap::fshutdownsocket`, `soap::fsend`, `soap::frecv`, `soap::fpoll`.

#define WITH_NONAMESPACES

When this macro is defined at compile time (undefined by default), removes dependence on the global `namespaces` table, rather users must set the XML namespaces explicitly by calling `soap_set_namespaces`

Applications developed with soapcpp2 options `-i` or `-j` assign a namespace table automatically to the `soap` context when the proxy or service object is instantiated. Other applications must set the namespace table explicitly, before processing XML, for example:

#include "soapH.h"
struct Namespace my_namespaces[] = {
{ "SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/", "http://www.w3.org/*soap-envelope", NULL },
{ "SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/", "http://www.w3.org/*soap-encoding", NULL },
{ "xsi", "http://www.w3.org/2001/XMLSchema-instance", "http://www.w3.org/*XMLSchema-instance", NULL },
{ "xsd", "http://www.w3.org/2001/XMLSchema", "http://www.w3.org/*XMLSchema", NULL },
{ "ns", "http://tempuri.org/ns.xsd", NULL, NULL },
{ NULL, NULL, NULL, NULL }
};
struct soap *soap = soap_new();
soap_set_namespaces(soap, my_namespaces); // use a specific XML namespace binding table for the next call
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
{
soap_print_fault(soap, stderr);
}
else
{
...
}
soap_set_namespaces(soap, namespaces); // use the default XML namespace binding table, when defined, for the next call

This example defines SOAP 1.1 namespaces (`SOAP-ENV` and `SOAP-ENC`) to be used by default, but also accepts SOAP 1.2 because of the second URI in the third column. XML schema instance namespace `xsi` is used with `xsi:type` and `xsi:nil` and the XML schema namespace `xsd` is used with XSD types such as `xsd:string`, which may be used in XML messages. URI patterns in the third column may contain wildcard strings `*` and wildcard characters `-`.

Examples:

      c++ -D WITH_NONAMESPACES -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_NONAMESPACES -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

#define WITH_NOZONE

When this macro is defined at compile time (undefined by default), removes and ignores the timezone in `xsd:dateTime` values.

Examples:

      c++ -D WITH_NOZONE -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
      c++ -D WITH_NOZONE -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

#define WITH_NTLM

When this macro is defined at compile time (undefined by default), enables linkage with the ntlm library for HTTP NTLM authentication.

The libntlm library is available at http://www.nongnu.org/libntlm and required for non-Windows platforms.

Examples:

      c++ -D WITH_NTLM -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp -lntlm
      c++ -D WITH_NTLM -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp -lntlm

See also
  `soap::ntlm_challenge`.

#define WITH_OPENSSL

When this macro is defined at compile time (undefined by default), enables activation and linkage with OpenSSL for HTTPS and WS-Security (this macro should also be defined when using plugins that rely on OpenSSL)

OpenSSL 3.0 and 1.1 are supported. Earlier OpenSSL versions are also supported, but not recommended.

Alternatives to OpenSSL are GNUTLS and WolfSSL with `WITH_GNUTLS` or `WITH_WOLFSSL`.

Use the following functions to configure SSL/TLS connections and to accept SSL/TLS connections:

- `soap_ssl_init`
- `soap_ssl_noinit`
- `soap_ssl_client_context`
- `soap_ssl_server_context`
- `soap_ssl_crl`
- `soap_ssl_accept`

Examples:

      c++ -D WITH_OPENSSL -D WITH_DOM -o client stdsoap2.cpp dom.cpp soapC.cpp soapClient.cpp client.cpp plugin/smdevp.c plugin/mecevp.c plugin/wsseapi.c plugin/threads.c -lcrypto -lssl
      c++ -D WITH_OPENSSL -D WITH_DOM -o server stdsoap2.cpp dom.cpp soapC.cpp soapServer.cpp server.cpp plugin/smdevp.c plugin/mecevp.c plugin/wsseapi.c plugin/threads.c -lcrypto -lssl

#define WITH_PURE_VIRTUAL

When this macro is defined at compile time (undefined by default), makes C++ service class operation methods and the copy method pure virtual by defining `SOAP_PURE_VIRTUAL` = 0.

Alternatively, use `WITH_DEFAULT_VIRTUAL` to make C++ service class operation methods return `SOAP_NO_METHOD` for rapid Web API prototyping and development.

Note
  Requires `soapcpp2 -j` option `-j` or option `-i` to generate C++ service classes.

Example:

      soapcpp2 -j myservice.h
      c++ -D WITH_PURE_VIRTUAL -o server stdsoap2.cpp soapC.cpp soapexampleService.cpp server.cpp

  // example myservice.h file for soapcpp2
  //gsoap ns service name: example
  //gsoap ns service namespace: urn:example
  struct ns__webmethodResponse {
  char *string;
  };
  int ns__webmethod(char *string, struct ns__webmethodResponse *response);
  // example server.cpp file
  #include "soapexampleService.h"
  #include "example.nsmap"
  class MyService : public exampleService {
  public:
  virtual int webmethod(char *string, struct ns__webmethodResponse *response)
  {
  response->string = string;
  return SOAP_OK;
  }
  virtual MyService *copy()
  {
  return new MyService(); // new instance, nothing shared or copied
  }
  };
  int main()
  {
  return MyService().run(PORTNUM);
  }

See also
  `WITH_DEFAULT_VIRTUAL`.

#define WITH_REPLACE_ILLEGAL_UTF8

When this macro is defined at compile time (undefined by default), replaces UTF-8 content that is outside the Unicode range with the value of `SOAP_UNKNOWN_UNICODE_CHAR` (Unicode FFFD) to indicate illegal UTF-8, set `SOAP_UNKNOWN_UNICODE_CHAR` to another integer code if desired (the value is 0xFFFD by default)

Warning
  Without this macro the engine silently accepts UTF-8 content that is outside the Unicode character ranges U+0000 to U+D7FF, U+E000 to U+FFFD, U+10000 to U+10FFFF.

Example:

      c++ -D WITH_REPLACE_ILLEGAL_UTF8 -c stdsoap2.cpp

See also
  `SOAP_UNKNOWN_UNICODE_CHAR`.

#define WITH_SELF_PIPE

When this macro is defined at compile time (undefined by default), the engine is configured to enable `soap_close_connection` using a "self-pipe".

To use `soap_close_connection` from another thread to terminate a thread that is blocked on socket IO requires `soap::recv_timeout` and `soap::send_timeout` set to nonzero timeout values.

Warning
  When this macro is define at the compiler's command line or in an IDE or by specifying `SOAPDEFS_H`, then all source code files of an application's project must be recompiled. Otherwise, `soap` context corruption errors may occur in the non-recompiled parts of the application, because the size of the `soap` context has changed.

Example:

      c++ -D WITH_SELF_PIPE -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp

See also
  `soap_close_connection`.

#define WITH_SOAPDEFS_H

When this macro is defined at compile time (undefined by default), a user-supplied file named soapdefs.h is included in the build, i.e. soapdefs.h can be used to configure the build by defining compile-time macros and flags.

Example:

      cat soapdefs.h
      #define WITH_OPENSSL
      #define WITH_DOM
      c++ -D WITH_SOAPDEFS_H -o client stdsoap2.cpp dom.cpp soapC.cpp soapClient.cpp client.cpp -lcrypto -lssl

Alternatively, set `SOAPDEFS_H` to the header file name to include in your build. For example:

    cat mydefs.h
    #define WITH_OPENSSL
    #define WITH_DOM
    c++ -D SOAPDEFS_H=mydefs.h -o client stdsoap2.cpp dom.cpp soapC.cpp soapClient.cpp client.cpp -lcrypto -lssl

#define WITH_SOCKET_CLOSE_ON_EXIT

When this macro is defined at compile time (undefined by default), prevents a server port from staying in listening mode after exit by internally setting `fcntl(sock, F_SETFD, FD_CLOEXEC)`

Example:

      c++ -D WITH_SOCKET_CLOSE_ON_EXIT -c stdsoap2.cpp

#define WITH_SSL_FULL_SHUTDOWN

When this macro is defined at compile time (undefined by default), the engine calls `SSL_shutdown(ssl)` twice, the second after `close_notify` (with a 5 second timeout), before closing the socket (`WITH_LEAN` n/a: calls `SSL_shutdown(ssl)` a second time without any timeout)

Example:

      c++ -D WITH_SSL_FULL_SHUTDOWN -c stdsoap2.cpp

#define WITH_TCPFIN

When this macro is defined at compile time (undefined by default), the engine transmits TCP FIN using `shutdown(sock, SHUT_WR)` after all sends are completed and just before the socket closes.

Example:

      c++ -D WITH_TCPFIN -c stdsoap2.cpp

#define WITH_WOLFSSL

When this macro is defined at compile time (undefined by default), enables activation and linkage of the WolfSSL library to enable HTTPS in the engine.

Use the following functions to configure SSL/TLS connections and to accept SSL/TLS connections:

- `soap_ssl_init`
- `soap_ssl_noinit`
- `soap_ssl_client_context`
- `soap_ssl_server_context`
- `soap_ssl_crl`
- `soap_ssl_accept`

Examples:

      c++ -D WITH_WOLFSSL -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp -lwolfssl
      c++ -D WITH_WOLFSSL -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp -lwolfssl

Link with libwolfssl.

#define WITH_ZLIB

When this macro is defined at compile time (undefined by default), enables linking the zlib library for HTTP message compression when the `SOAP_ENC_ZLIB` mode flag is enabled at runtime.

To enable (de)compression with the compress method use `SOAP_ENC_ZLIB`:

#include "soapH.h"
struct soap *soap = soap_new1(SOAP_ENC_ZLIB);

Examples:

      c++ -D WITH_ZLIB -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp -lz
      c++ -D WITH_ZLIB -o server stdsoap2.cpp soapC.cpp soapServer.cpp server.cpp -lz

See also
  `WITH_GZIP` to also enable the gzip compression method in addition to compress.