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:

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:

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

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

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:

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:

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:

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:

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.

Macros

Detailed Description

Macro Definition Documentation