This module defines the SOAP_MACRO compile-time values to configure the engine build. More...

Macros
#define	SOAP_NOTHROW (std::nothrow)
	Macro expands to `(std::nothrow)` to prevent the deserializer's memory allocator from throwing an exception but return `SOAP_EOM` instead, this macro is empty when `WITH_COMPAT` is enabled or when `WITH_LEAN` or `WITH_LEANER` are enabled which means that exceptions may be thrown. More...

#define	SOAP_BUFLEN (65536)
	User-definable size of the input and output message buffer `soap::buf` (the value is 65536 by default) More...

#define	SOAP_HDRLEN (8192)
	User-definable maximum length of HTTP headers (the value is 8192 by default) More...

#define	SOAP_TAGLEN (1024)
	User-definable maximum length of XML tags and URLs (the value is 1024 by default) More...

#define	SOAP_TMPLEN (1024)
	User-definable maximum length of temporary string values stored in `soap::msgbuf` and `soap::tmpbuf`, e.g. to hold short strings and brief error messages (1024 by default, must not be less than 1024) More...

#define	SOAP_MAXALLOCSIZE (0)
	User-definable maximum size of a block of memory that `malloc` can allocate or 0 for no limit (the value is 0 by default) More...

#define	SOAP_MAXARRAYSIZE (100000)
	User-definable macro to protect excessive SOAP array allocation requests by defining a maximum allocation threshold. More...

#define	SOAP_MAXDIMESIZE (8*1048576)
	User-definable maximum length of DIME attachments received (the value is 8 MB by default) More...

#define	SOAP_MAXEINTR (10)
	User-definable maximum number of EINTR interrupts to ignore while polling a socket for pending activity, each EINTR ignored may increase the I/O blocking time by at most one second (the value is 10 by default) More...

#define	SOAP_MAXINFLATESIZE (1*1048576)
	Trusted inflated content size (1 MB by default), larger content is subject to the `SOAP_MINDEFLATERATIO` constraint, i.e. if `SOAP_MINDEFLATERATIO` is 1.0, `SOAP_MAXINFLATESIZE` is always the max size of uncompressed content. More...

#define	SOAP_MAXKEEPALIVE (100)
	User-definable maximum iterations in the server-side `soap_serve` loop (or the C++ service class `serve` method) on HTTP keep-alive connections, assigned to `soap::max_keep_alive` which can be altered at runtime (the value is 100 by default) More...

#define	SOAP_MAXLENGTH (0)
	User-definable maximum string content length for strings not already constrained by XML schema validation constraints, zero or negative means unlimited string lengths are allowed (the value is 0 by default) More...

#define	SOAP_MAXLEVEL (10000)
	User-definable maximum XML nesting depth level permitted by the XML parser, must be greater than zero (the value is 10000 by default) More...

#define	SOAP_MAXOCCURS (100000)
	User-definable maximum number of array or container elements for containers that are not already constrained by XML schema validation constraints, must be greater than zero (the value is 100000 by default) More...

#define	SOAP_MAXHTTPCHUNK (2147483647)
	User-definable maximum HTTP chunk size receivable (the value is 2147483647 by default), also HTTP chunk sizes cannot exceed `soap::recv_maxlength`. More...

#define	SOAP_MINDEFLATERATIO (1.0/1032.0)
	Trusted deflation ratio after `SOAP_MAXINFLATESIZE` is reached, trust when compressed / deflated > `SOAP_MINDEFLATERATIO` (default is 0.00096899224806 or 1032:1, which is according to the zlib site: "The limit (1032:1) comes from the fact that one length/distance pair can represent at most 258 output bytes. A length requires at least one bit and a distance requires at least one bit, so two bits in can give 258 bytes out, or eight bits in give 1032 bytes out. A dynamic block has no length restriction, so you could get arbitrarily close to the limit of 1032:1.". More...

#define	SOAP_PURE_VIRTUAL = 0
	Macro is set to `SOAP_PURE_VIRTUAL` = 0 at compile time when macro `WITH_PURE_VIRTUAL` is defined. More...

#define	SOAP_SSL_RSA_BITS (2048)
	User-definable length of RSA keys used for https connections (the value is 2048 by default), ignored with OpenSSL v3. More...

#define	SOAP_UNKNOWN_CHAR (0x7F)
	User-definable 8 bit integer that represents a character that could not be converted to an ASCII char, i.e. when converting an XML Unicode character (typically UTF-8), this is applicable when the runtime flag `SOAP_C_UTFSTRING` is not used (the value is 0x7F by default) More...

#define	SOAP_UNKNOWN_UNICODE_CHAR (0xFFFD)
	A user-definable integer Unicode value representing a character that replaces an invalid Unicode code point, i.e. when converting an XML invalid Unicode character from UTF-8 (the value is 0xFFFD by default) More...

#define	SOAP_LONG_FORMAT "%lld"
	User-definable macro that represents the `LONG64` printf %-format. More...

#define	SOAP_ULONG_FORMAT "%llu"
	User-definable macro that represents the `ULONG64` printf %-format. More...

#define	SOAP_SOCKET int
	Macro that defines a portable socket type, usually `int`, but the type may depend on the platform being used. More...

#define	SOAP_INVALID_SOCKET (-1)
	Macro that defines a portable invalid socket value (usually -1, but the value depends on the OS) More...

#define	SOAP_SOCKLEN_T size_t
	Macro that defines a portable socklen_t type (usually `size_t`, but type depends on the OS) More...

#define	soap_valid_socket(sock) ((sock) != SOAP_INVALID_SOCKET)
	Function macro to check if a socket is valid, i.e. not equal to `SOAP_INVALID_SOCKET` More...

#define	LONG64 int64_t
	User-definable macro that represents a portable signed 64 bit integer type. More...

#define	ULONG64 uint64_t
	User-definable macro that represents a portable unsigned 64 bit integer type. More...

#define	FLT_NAN
	User-definable macro that represents a portable single floating point NaN value (defined by default to a platform-specific NaN value) More...

#define	FLT_PINFTY
	User-definable macro that represents a portable single floating point positive infinite value (defined by default to a platform-specific value) More...

#define	FLT_NINFTY
	User-definable macro that represents a portable single floating point negative infinite value (defined by default to a platform-specific value) More...

#define	DBL_NAN
	User-definable macro that represents a portable double floating point NaN value (defined by default to a platform-specific NaN value) More...

#define	DBL_PINFTY
	User-definable macro that represents a portable double floating point positive infinite value (defined by default to a platform-specific value) More...

#define	DBL_NINFTY
	User-definable macro that represents a portable double floating point negative infinite value (defined by default to a platform-specific value) More...

#define	soap_isnan(x)
	Macro that returns true if the floating point value is NaN. More...

#define	soap_isinf(x)
	Macro that returns true if the floating point value is infinity. More...

#define	SOAP_MALLOC(soap, size) malloc((size))
	User-definable macro to override malloc() for context-managed heap allocation (excluding C++ class instances, see `SOAP_NEW`) More...

#define	SOAP_FREE(soap, ptr) free((void*)(ptr))
	User-definable macro to override free() for context-managed heap allocation (excluding C++ class instances, see `SOAP_DELETE`) More...

#define	SOAP_MALLOC_UNMANAGED(soap, size) malloc((size))
	User-definable macro to override malloc() for unmanaged heap allocation. More...

#define	SOAP_FREE_UNMANAGED(soap, ptr) free((void*)(ptr))
	User-definable macro to override free() for unmanaged heap allocation. More...

#define	SOAP_NEW(soap, type) new SOAP_NOTHROW (type)
	User-definable macro to override C++ new. More...

#define	SOAP_NEW_ARRAY(soap, type, n) new SOAP_NOTHROW type[n]
	User-definable macro to override C++ new for arrays. More...

#define	SOAP_PLACEMENT_NEW(soap, buf, type) new (buf) (type)
	User-definable macro to override C++ placement new. More...

#define	SOAP_DELETE(soap, obj, type) delete obj
	User-definable macro to override C++ delete. More...

#define	SOAP_DELETE_ARRAY(soap, obj, type) delete[] obj
	User-definable macro to override C++ delete for arrays. More...

#define	SOAP_NEW_UNMANAGED(soap) new SOAP_NOTHROW soap
	User-definable macro to override C++ new for unmanaged allocation of the soap context. More...

#define	SOAP_DELETE_UNMANAGED(soap) delete soap
	User-definable macro to override C++ delete for unmanaged deallocation of the soap context. More...

#define	SOAP_STD_EXPORTS
	User-definable macro to enable Windows DLL builds. More...

#define	SOAP_FMAC1
	User-definable macro to annotate global functions. More...

#define	SOAP_FMAC2
	User-definable macro to annotate global functions. More...

#define	SOAP_FMAC3
	User-definable macro to annotate global serialization functions generated by soapcpp2. More...

#define	SOAP_FMAC4
	User-definable macro to annotate global serialization functions generated by soapcpp2. More...

#define	SOAP_FMAC5
	User-definable macro to annotate global service functions generated by soapcpp2. More...

#define	SOAP_FMAC6
	User-definable macro to annotate global service functions generated by soapcpp2. More...

#define	SOAP_CMAC
	User-definable macro to annotate class definitions. More...

#define	SOAP_NMAC
	User-definable macro to annotate namespace table definitions. More...

Detailed Description

This module defines the SOAP_MACRO compile-time values to configure the engine build.

This module defines the following macros with values to configure the engine build:

Integer and float type macros:

Macros for heap allocation:

DLL and API export related macros:

Macro Definition Documentation

#define DBL_NAN

User-definable macro that represents a portable double floating point NaN value (defined by default to a platform-specific NaN value)

#define DBL_NINFTY

User-definable macro that represents a portable double floating point negative infinite value (defined by default to a platform-specific value)

#define DBL_PINFTY

User-definable macro that represents a portable double floating point positive infinite value (defined by default to a platform-specific value)

#define FLT_NAN

User-definable macro that represents a portable single floating point NaN value (defined by default to a platform-specific NaN value)

#define FLT_NINFTY

User-definable macro that represents a portable single floating point negative infinite value (defined by default to a platform-specific value)

#define FLT_PINFTY

User-definable macro that represents a portable single floating point positive infinite value (defined by default to a platform-specific value)

#define LONG64 int64_t

User-definable macro that represents a portable signed 64 bit integer type.

Legacy platforms that do not support 64 bit types can still be used by redefining LONG64 to int. For example:

cc -D LONG64=int -D ULONG64="unsigned int" -D SOAP_LONG_FORMAT='"%d"' -D SOAP_ULONG_FORMAT='"%u"' -o client stdsoap2.c soapC.c soapClient.c client.c

This type is also available as a valid type to use in the .h file for soapcpp2.

See also: ULONG64, SOAP_LONG_FORMAT, SOAP_ULONG_FORMAT.

#define SOAP_BUFLEN (65536)

User-definable size of the input and output message buffer soap::buf (the value is 65536 by default)

This macro defines the size of the input and output message buffer, which is 65536 by default unless the WITH_LEAN or WITH_LEANER compile-time flags are used and the buffer size is 2048. The size of the buffer affects the performance of socket communications, with larger sizes above 8192 generally improving the performance at the cost of the extra memory required to store the larger soap context.

A default value of 65535 was chosen for OpenVMS TCP/IP stacks that cannot handle 65536 bytes. A default value of 2048 is used for WinCE platforms. A default value of 32767 is used for Tandom NonStop platforms.

Warning: When the value of this macro is assigned 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.

#define SOAP_CMAC

User-definable macro to annotate class definitions.

The soapcpp2 tool generates struct and class definitions as follows:

class SOAP_CMAC name { ... };

#define SOAP_DELETE	(	soap,
		obj,
		type
	)	delete obj

User-definable macro to override C++ delete.

#define SOAP_DELETE_ARRAY	(	soap,
		obj,
		type
	)	delete[] obj

User-definable macro to override C++ delete for arrays.

#define SOAP_DELETE_UNMANAGED ( soap ) delete soap

User-definable macro to override C++ delete for unmanaged deallocation of the soap context.

#define SOAP_FMAC1

User-definable macro to annotate global functions.

See also: SOAP_STD_EXPORTS, SOAP_FMAC2.

#define SOAP_FMAC2

User-definable macro to annotate global functions.

This macro is used in combination with SOAP_FMAC1.

See also: SOAP_FMAC1.

#define SOAP_FMAC3

User-definable macro to annotate global serialization functions generated by soapcpp2.

The soapcpp2 tool generates serialization functions as follows:

SOAP_FMAC3 int SOAP_FMAC4 soap_out_int(struct soap *soap, const char *tag, int id, const int *ptr, const char *type);
SOAP_FMAC3 int * SOAP_FMAC4 soap_in_int(struct soap *soap, const char *tag, int *ptr, const char *type);
SOAP_FMAC3 int * SOAP_FMAC4 soap_new_int(struct soap *soap, int num);
SOAP_FMAC3 int SOAP_FMAC4 soap_put_int(struct soap *soap, const int *ptr, const char *tag, const char *type);
SOAP_FMAC3 int * SOAP_FMAC4 soap_get_int(struct soap *soap, int *ptr, const char *tag, const char *type);

Other serialization functions are generated as well, either as C++ inlines or C defines.

See also: SOAP_STD_EXPORTS, SOAP_FMAC4.

#define SOAP_FMAC4

User-definable macro to annotate global serialization functions generated by soapcpp2.

This macro is used in combination with SOAP_FMAC3.

See also: SOAP_FMAC3.

#define SOAP_FMAC5

User-definable macro to annotate global service functions generated by soapcpp2.

The soapcpp2 tool generates service functions as follows at the client and service sides, respectively:

SOAP_FMAC5 int SOAP_FMAC6 soap_call_ns__webmethod(struct soap *soap, ...) { ... }

SOAP_FMAC5 int SOAP_FMAC6 soap_serve_ns__webmethod(struct soap *soap)

See also: SOAP_STD_EXPORTS, SOAP_FMAC6.

#define SOAP_FMAC6

User-definable macro to annotate global service functions generated by soapcpp2.

This macro is used in combination with SOAP_FMAC5.

See also: SOAP_FMAC5.

#define SOAP_FREE	(	soap,
		ptr
	)	free((void*)(ptr))

User-definable macro to override free() for context-managed heap allocation (excluding C++ class instances, see SOAP_DELETE)

#define SOAP_FREE_UNMANAGED	(	soap,
		ptr
	)	free((void*)(ptr))

User-definable macro to override free() for unmanaged heap allocation.

#define SOAP_HDRLEN (8192)

User-definable maximum length of HTTP headers (the value is 8192 by default)

Warning: When the value of this macro is assigned 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.

#define SOAP_INVALID_SOCKET (-1)

Macro that defines a portable invalid socket value (usually -1, but the value depends on the OS)

See also: soap_valid_socket.

#define soap_isinf ( x )

Macro that returns true if the floating point value is infinity.

#define soap_isnan ( x )

Macro that returns true if the floating point value is NaN.

#define SOAP_LONG_FORMAT "%lld"

User-definable macro that represents the LONG64 printf %-format.

This macro is "%lld" or "%I64d" on Windows.

#define SOAP_MALLOC	(	soap,
		size
	)	malloc((size))

User-definable macro to override malloc() for context-managed heap allocation (excluding C++ class instances, see SOAP_NEW)

#define SOAP_MALLOC_UNMANAGED	(	soap,
		size
	)	malloc((size))

User-definable macro to override malloc() for unmanaged heap allocation.

#define SOAP_MAXALLOCSIZE (0)

User-definable maximum size of a block of memory that malloc can allocate or 0 for no limit (the value is 0 by default)

#define SOAP_MAXARRAYSIZE (100000)

User-definable macro to protect excessive SOAP array allocation requests by defining a maximum allocation threshold.

Deserialized SOAP arrays larger in size than SOAP_MAXARRAYSIZE are not pre-allocated in memory, but deserialized on an element-by-element basis until XML validation contrains kick in (the value is 100000 by default)

#define SOAP_MAXDIMESIZE (8*1048576)

User-definable maximum length of DIME attachments received (the value is 8 MB by default)

DIME attachments sizes are limited to SOAP_MAXDIMESIZE. Increase this value to allow larger attachments or decrease when resources are limited, this limit is to deny senders to pre-allocate excessive memory at the receiver side without actually sending the whole message, i.e. this threshold protects against DIME-based memory resource usage attacks.

#define SOAP_MAXEINTR (10)

User-definable maximum number of EINTR interrupts to ignore while polling a socket for pending activity, each EINTR ignored may increase the I/O blocking time by at most one second (the value is 10 by default)

#define SOAP_MAXHTTPCHUNK (2147483647)

User-definable maximum HTTP chunk size receivable (the value is 2147483647 by default), also HTTP chunk sizes cannot exceed soap::recv_maxlength.

#define SOAP_MAXINFLATESIZE (1*1048576)

Trusted inflated content size (1 MB by default), larger content is subject to the SOAP_MINDEFLATERATIO constraint, i.e. if SOAP_MINDEFLATERATIO is 1.0, SOAP_MAXINFLATESIZE is always the max size of uncompressed content.

#define SOAP_MAXKEEPALIVE (100)

User-definable maximum iterations in the server-side soap_serve loop (or the C++ service class serve method) on HTTP keep-alive connections, assigned to soap::max_keep_alive which can be altered at runtime (the value is 100 by default)

#define SOAP_MAXLENGTH (0)

User-definable maximum string content length for strings not already constrained by XML schema validation constraints, zero or negative means unlimited string lengths are allowed (the value is 0 by default)

#define SOAP_MAXLEVEL (10000)

User-definable maximum XML nesting depth level permitted by the XML parser, must be greater than zero (the value is 10000 by default)

#define SOAP_MAXOCCURS (100000)

User-definable maximum number of array or container elements for containers that are not already constrained by XML schema validation constraints, must be greater than zero (the value is 100000 by default)

#define SOAP_MINDEFLATERATIO (1.0/1032.0)

Trusted deflation ratio after SOAP_MAXINFLATESIZE is reached, trust when compressed / deflated > SOAP_MINDEFLATERATIO (default is 0.00096899224806 or 1032:1, which is according to the zlib site: "The limit (1032:1) comes from the fact that one length/distance pair can represent at most 258 output bytes. A length requires at least one bit and a distance requires at least one bit, so two bits in can give 258 bytes out, or eight bits in give 1032 bytes out. A dynamic block has no length restriction, so you could get arbitrarily close to the limit of 1032:1.".

#define SOAP_NEW	(	soap,
		type
	)	new SOAP_NOTHROW (type)

User-definable macro to override C++ new.

#define SOAP_NEW_ARRAY	(	soap,
		type,
		n
	)	new SOAP_NOTHROW type[n]

User-definable macro to override C++ new for arrays.

#define SOAP_NEW_UNMANAGED ( soap ) new SOAP_NOTHROW soap

User-definable macro to override C++ new for unmanaged allocation of the soap context.

#define SOAP_NMAC

User-definable macro to annotate namespace table definitions.

The soapcpp2 tool generates Namespace tables with XML namespace bindings which are declared as follows:

SOAP_NMAC struct Namespace namespaces[] = { ... };

#define SOAP_NOTHROW (std::nothrow)

Macro expands to (std::nothrow) to prevent the deserializer's memory allocator from throwing an exception but return SOAP_EOM instead, this macro is empty when WITH_COMPAT is enabled or when WITH_LEAN or WITH_LEANER are enabled which means that exceptions may be thrown.

It is possible to enable C++ exceptions without detrimental effects by compiling the source code with SOAP_NOTHROW set to an empty value and in that case C++ exception handlers should be used to catch std::bad_alloc.

By default, soap_new and the soapcpp2-generated soap_new_T functions return NULL when allocation failed.

Warning: soap_malloc never throws std::bad_alloc, which means that parsing and deserialization of C++ data may not throw std::bad_alloc in some cases, but rather the functions called will return SOAP_EOM and soap::error is set to SOAP_EOM. soap_malloc also returns SOAP_EOM when SOAP_MAXALLOCSIZE is exceeded.

Example:

c++ -D SOAP_NOTHROW="" -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp

// compiled with compile-time flag -D SOAP_NOTHROW=""
#include "soapH.h"
try
{
  // soap_new() may cause a std::bad_alloc exception
  struct soap *soap = soap_new();
  // MyClass is declared in soapH.h generated by soapcpp2 from a .h file with MyClass
  MyClass *obj = soap_new_MyClass(soap);
  ... // use obj
}
catch (std::bad_alloc)
{
  ... // out of memory error
}

#define SOAP_PLACEMENT_NEW	(	soap,
		buf,
		type
	)	new (buf) (type)

User-definable macro to override C++ placement new.

#define SOAP_PURE_VIRTUAL = 0

Macro is set to SOAP_PURE_VIRTUAL = 0 at compile time when macro WITH_PURE_VIRTUAL is defined.

#define SOAP_SOCKET int

Macro that defines a portable socket type, usually int, but the type may depend on the platform being used.

#define SOAP_SOCKLEN_T size_t

Macro that defines a portable socklen_t type (usually size_t, but type depends on the OS)

#define SOAP_SSL_RSA_BITS (2048)

User-definable length of RSA keys used for https connections (the value is 2048 by default), ignored with OpenSSL v3.

#define SOAP_STD_EXPORTS

User-definable macro to enable Windows DLL builds.

This macro when set exports global functions and classes by defining SOAP_FMAC1, SOAP_FMAC3, SOAP_FMAC5, and SOAP_CMAC to __declspec(dllexport).

Example:

C:> soapcpp2.exe -penv env.h
C:> cl /c /I. /EHsc /DWITH_NONAMESPACES /DSOAP_STD_EXPORTS envC.cpp stdsoap2.cpp
C:> link /LIBPATH ws2_32.lib /OUT:mygsoap.dll /DLL envC.obj stdsoap2.obj

#define SOAP_TAGLEN (1024)

User-definable maximum length of XML tags and URLs (the value is 1024 by default)

Warning: When the value of this macro is assigned 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.

#define SOAP_TMPLEN (1024)

User-definable maximum length of temporary string values stored in soap::msgbuf and soap::tmpbuf, e.g. to hold short strings and brief error messages (1024 by default, must not be less than 1024)

Warning: When the value of this macro is assigned 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.

#define SOAP_ULONG_FORMAT "%llu"

User-definable macro that represents the ULONG64 printf %-format.

This macro is "%llu" or "%I64u" on Windows.

#define SOAP_UNKNOWN_CHAR (0x7F)

User-definable 8 bit integer that represents a character that could not be converted to an ASCII char, i.e. when converting an XML Unicode character (typically UTF-8), this is applicable when the runtime flag SOAP_C_UTFSTRING is not used (the value is 0x7F by default)

#define SOAP_UNKNOWN_UNICODE_CHAR (0xFFFD)

A user-definable integer Unicode value representing a character that replaces an invalid Unicode code point, i.e. when converting an XML invalid Unicode character from UTF-8 (the value is 0xFFFD by default)

#define soap_valid_socket ( sock ) ((sock) != SOAP_INVALID_SOCKET)

Function macro to check if a socket is valid, i.e. not equal to SOAP_INVALID_SOCKET

#define ULONG64 uint64_t

User-definable macro that represents a portable unsigned 64 bit integer type.

Legacy platforms that do not support 64 bit types can still be used by redefining LONG64 to int. For example:

cc -D LONG64=int -D ULONG64="unsigned int" -D SOAP_LONG_FORMAT='"%d"' -D SOAP_ULONG_FORMAT='"%u"' -o client stdsoap2.c soapC.c soapClient.c client.c

This type is also available as a valid type to use in the .h file for soapcpp2.

See also: LONG64, SOAP_LONG_FORMAT, SOAP_ULONG_FORMAT.