|  | Home | Documentation | WITH_MACRO compile-time flags updated by Robert van Engelen |

WITH_MACRO compile-time flags

This module describes 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.
#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.
#define | WITH_COMPAT
| When this macro is defined at compile time (undefined by default), removes dependency on C++ std::string and std::iostream libraries.
#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.
#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.
#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).
#define | WITH_COOKIES
| When this macro is defined at compile time (undefined by default), HTTP cookie support is enabled in the engine.
#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.
#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.
#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.
#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).
#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.
#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.
#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.
#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.
#define | WITH_NTLM
| When this macro is defined at compile time (undefined by default), enables linkage with the ntlm library for HTTP NTLM authentication.
#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.
#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.
#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_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.
#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).
#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.
#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.
#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.
#define | WITH_NOHTTP
| When this macro is defined at compile time (undefined by default), permanently removes the HTTP stack to reduce code size.
#define | WITH_NOZONE
| When this macro is defined at compile time (undefined by default), removes and ignores the timezone in xsd:dateTime values.
#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.
#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.
#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.
#define | WITH_CDATA
| When this macro is defined at compile time (undefined by default), retains the parsed CDATA sections in literal XML strings.
#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.
#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.
#define | WITH_CASEINSENSITIVETAGS
| When this macro is defined at compile time (undefined by default), enables case insensitive XML tag name parsing and validation.
#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).
#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.
#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).
#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".
#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.
#define | WITH_POSIX_STRERROR_R
| When this macro is defined at compile time (undefined by default), the XSI-compliant POSIX version of strerror_r is expected instead of the GNU-specific strerror_r.

## Detailed Description

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

This module describes 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
- #WITH_POSIX_STRERROR_R

## Macro Definition Documentation

## ◆ SOAPDEFS_H

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

## ◆ WITH_C_LOCALE

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

## ◆ WITH_CASEINSENSITIVETAGS

#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

## ◆ WITH_CDATA

#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)
  _XML
  *A built in string type containing literal XML content in UTF format typedef char * _XML
  Definition stdsoap2.h:5205
  // 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);
  soap_free
  *Finalize and free the given ::soap context from unmanaged heap memory void soap_free(struct soap *soap)
  soap_end
  *Delete all data from heap memory managed by the specified ::soap context and release the freed memory back to the heap int soap_end(struct soap *soap) * @returns `
  soap_print_fault
  void soap_print_fault(struct soap *soap, FILE *fd)
  Print error message on the specified output.
  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
  Context with the engine state.
  Definition stdsoap2.h:2929
  soap::endpoint
  char endpoint[SOAP_TAGLEN]
  The endpoint URL as received on the server side.
  Definition stdsoap2.h:4143
  Request and response messages:
  <?xml version="1.0" encoding="UTF-8"?>
  <SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:ns="urn:example">
  <SOAP-ENV:Body>
  <ns:webmethod>
  <doc title="Example">Some text</doc>
  </ns:webmethod>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>
  <?xml version="1.0" encoding="UTF-8"?>
  <SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:ns="urn:example">
  <SOAP-ENV:Body>
  <ns:webmethodResponse>
  <![CDATA[<doc title="Example">Some text</doc>]]>
  </ns:webmethodResponse>
  </SOAP-ENV:Body>
  </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>

## ◆ WITH_COMPAT

#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

## ◆ WITH_COOKIES

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

## ◆ WITH_CRTOLF

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

## ◆ WITH_DEFAULT_VIRTUAL

#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);
  }
  SOAP_OK
  #define SOAP_OK
  The soap_status code for no error (zero).
  Definition stdsoap2.h:2392

## ◆ WITH_DOM

#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
}
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::dom
*DOM tree received struct soap_dom_element * dom
Definition stdsoap2.h:4304

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.

## ◆ WITH_FAST

#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

## ◆ WITH_FASTCGI

#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
  soap_serve
  *Bind and listen to a port SOAP_SOCKET soap_bind *(struct soap *soap, const char *host, int port, int backlog) * @returns the ` Accept a connection with a client SOAP_SOCKET soap_accept *(struct soap *soap) * @returns the ` Serve a pending request in soap_serve)(struct soap *soap) * @returns `
  Definition stdsoap2.h:7466

## ◆ WITH_GNUTLS

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

## ◆ WITH_GZIP

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

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.

## ◆ WITH_INCLUDE_XLOCALE_H

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

## ◆ WITH_INSECURE_COOKIES

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

## ◆ WITH_IPV6

#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)))
...
soap_valid_socket
#define soap_valid_socket(sock)
Function macro to check if a socket is valid, i.e. not equal to #SOAP_INVALID_SOCKET.
Definition stdsoap2.h:1354
soap::bind_inet6
short bind_inet6
User-definable flag, when nonzero uses AF_INET6 instead of PF_UNSPEC when binding the soap::master so...
Definition stdsoap2.h:3534
soap::bind_v6only
short bind_v6only
User-definable flag, when nonzero enables IPPROTO_IPV6 setsockopt IPV6_V6ONLY when binding the soap::...
Definition stdsoap2.h:3552

Example:

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

## ◆ WITH_IPV6_V6ONLY

#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

## ◆ WITH_LEAN

#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

## ◆ WITH_LEANER

#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

## ◆ WITH_NO_C_LOCALE

#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

## ◆ WITH_NOEMPTYNAMESPACES

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

## ◆ WITH_NOEMPTYSTRUCT

#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

## ◆ WITH_NOGLOBAL

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

## ◆ WITH_NOHTTP

#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

## ◆ WITH_NOIDREF

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

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.

## ◆ WITH_NOIO

#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;
soap::faccept
*Callback that waits for and accepts a socket connection requested by a client SOAP_SOCKET(* faccept)(struct soap *soap, SOAP_SOCKET sock, struct sockaddr *addr, int *len)
Definition stdsoap2.h:4649
soap::fshutdownsocket
*Callback that shuts down a given socket int(* fshutdownsocket)(struct soap *soap, SOAP_SOCKET sock, int how)
Definition stdsoap2.h:4723
soap::fopen
*Callback that opens a socket connection to a server endpoint SOAP_SOCKET(* fopen)(struct soap *soap, const char *endpoint, const char *host, int port)
Definition stdsoap2.h:4635
soap::frecv
*Callback that receives bytes of data into the given buffer size_t(* frecv)(struct soap *soap, char *buf, size_t len)
Definition stdsoap2.h:4747
soap::fclose
*Callback that closes the current socket connection int(* fclose)(struct soap *soap)
Definition stdsoap2.h:4660
soap::fsend
*Callback that sends the given bytes of data int(* fsend)(struct soap *soap, const char *data, size_t len)
Definition stdsoap2.h:4760
soap::fclosesocket
*Callback that closes a given socket int(* fclosesocket)(struct soap *soap, SOAP_SOCKET sock)
Definition stdsoap2.h:4710
soap::fpoll
*Callback that blocks until activity is detected on the ::soap::socket or ::soap::master times out when ::soap::send_timeout or ::soap::recv_timeout are set int(* fpoll)(struct soap *soap)
Definition stdsoap2.h:4734
SOAP_SOCKET
#define SOAP_SOCKET
Macro that defines a portable socket type, usually int, but the type may depend on the platform being...
Definition stdsoap2.h:1342

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.

## ◆ WITH_NONAMESPACES

#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
soap_set_namespaces
int soap_set_namespaces(struct soap *soap, const struct Namespace *namespaces)
Activates an XML namespace table to generate and resolve xmlns namespace prefixes in XML messages.
namespaces
struct Namespace namespaces[]
The global XML namespaces table with entries defined by the Namespace structure and populated in an ....
Definition stdsoap2.h:9447
Namespace
Structure of each row in a namespace table.
Definition stdsoap2.h:9432

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

## ◆ WITH_NOZONE

#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

## ◆ WITH_NTLM

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

## ◆ WITH_OPENSSL

#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

## ◆ WITH_POSIX_STRERROR_R

#define WITH_POSIX_STRERROR_R

When this macro is defined at compile time (undefined by default), the XSI-compliant POSIX version of strerror_r is expected instead of the GNU-specific strerror_r.

This macro affects compilation of stdsoap2.c and stdsoap2.cpp. On some systems such as Musl Linux the XSI-compliant POSIX version of strerror_r is not detectable at compile time and this may lead to compile-time errors for strerror_r mismatched return types. In this case, compile with -D WITH_POSIX_STRERROR_R. This feature requires version 2.8.139 or greater.

Example, when building the library and tools:

      ./configure CFLAGS=-DWITH_POSIX_STRERROR_R CXXFLAGS=-DWITH_POSIX_STRERROR_R

Example, when building from source:

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

## ◆ WITH_PURE_VIRTUAL

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

## ◆ WITH_REPLACE_ILLEGAL_UTF8

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

## ◆ WITH_SELF_PIPE

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

## ◆ WITH_SOAPDEFS_H

#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

## ◆ WITH_SOCKET_CLOSE_ON_EXIT

#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

## ◆ WITH_SSL_FULL_SHUTDOWN

#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

## ◆ WITH_TCPFIN

#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

## ◆ WITH_WOLFSSL

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

## ◆ WITH_ZLIB

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