README.md

Go to the documentation of this file.

C and C++ XML Data Bindings                                          {#mainpage}
===========================

[TOC]

Introduction                                                            {#intro}
============

This article presents a detailed overview of the gSOAP XML data bindings for C
and C++.  The XML data bindings for C and C++ are extensively used with gSOAP
Web services to serialize C and C++ data in XML as part of the SOAP/XML Web
services payloads.  Also REST XML with gSOAP relies on XML serialization of C
and C++ data via XML data bindings.

The major advantage of XML data bindings is that your application data is
always **type safe** in C and C++ by binding XML schema types to C/C++ types.
So integers in XML are bound to C integers, strings in XML are bound to C or
C++ strings, complex types in XML are bound to C structs or C++ classes, and so
on.  The structured data you create and accept will fit the data model and is
**static type safe**.  In other words, by leveraging strong typing in C/C++,
your XML data meets **XML schema validation requirements** and satisfies **XML
interoperability requirements**.

In fact, gSOAP data bindings are more powerful than simply representing C/C++
data in XML.  The gSOAP tools implement true and tested **structure-preserving
serialization** of C/C++ data in XML, including the serialization of cyclic
graph structures with id-ref XML attributes.  The gSOAP tools also generate
routines for deep copying and deep deletion of C/C++ data structures to
simplify memory management.  In addition, C/C++ structures are deserialized
into managed memory, managed by the gSOAP `soap` context.

At the end of this article two examples are given to illustrate the application
of XML data bindings.  The first simple example <i>`address.cpp`</i> shows how to use
wsdl2h to bind an XML schema to C++.  The C++ application reads and writes an
XML file into and from a C++ "address book" data structure as a simple example.
The C++ data structure is an STL vector of address objects.  The second example
<i>`graph.cpp`</i> shows how C++ data can be accurately serialized as a tree, digraph,
and cyclic graph in XML.  The digraph and cyclic graph serialization rules
implement SOAP 1.1/1.2 multi-ref encoding with id-ref attributes to link
elements through IDREF XML references, creating a an XML graph with pointers to
XML nodes that preserves the structural integrity of the serialized C++ data.

These examples demonstrate XML data bindings only for relatively simple data
structures and types.  The gSOAP tools support more than just these type of
structures to serialize in XML.  There are practically no limits to the
serialization of C and C++ data types in XML.

Also the support for XML schema (XSD) components is unlimited.  The wsdl2h tool
maps schemas to C and C++ using built-in intuitive mapping rules, while
allowing the mappings to be customized using a <i>`typemap.dat`</i> file with mapping
instructions for wsdl2h.

The information in this article is applicable to gSOAP 2.8.26 and greater that
support C++11 features.  However, C++11 is not required.  The material and the
examples in this article use plain C and C++, until the point where we
introduce C++11 smart pointers and scoped enumerations.  While most of the
examples in this article are given in C++, the concepts also apply to C with
the exception of containers, smart pointers, classes and their methods.  None
of these exceptions limit the use of the gSOAP tools for C in any way.

The data binding concepts described in this article were first envisioned in
1999 by Prof. Robert van Engelen at the Florida State University.  An
implementation was created in 2000, named "stub/skeleton compiler".  The first
articles on its successor version "gSOAP" appeared in 2002.  The principle of
mapping XSD components to C/C++ types and vice versa is now widely adopted in
systems and programming languages, including Java web services and by C# WCF.

We continue to be committed to our goal to empower C/C++ developers with
powerful autocoding tools for XML.  Our commitment started in the very early
days of SOAP by actively participating in
[SOAP interoperability testing](http://www.whitemesa.com/interop.htm),
participating in the development and testing of the
[W3C XML Schema Patterns for Databinding Interoperability](http://www.w3.org/2002/ws/databinding),
and continues by contributing to the development of
[OASIS open standards](https://www.oasis-open.org) in partnership with leading
IT companies in the world.

🔝 [Back to table of contents](#)

Notational Conventions                                            {#conventions}
======================

The typographical conventions used by this document are:

* `Courier` denotes C and C++ source code.

* <i>`Courier`</i> denotes XML content, JSON content, file and path names, and URIs.

* <b>`Courier`</b> denotes HTTP content, text file content, and shell commands with command line options and arguments.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to
be interpreted as described in RFC-2119.

🔝 [Back to table of contents](#)

Mapping WSDL and XML schemas to C/C++                                   {#tocpp}
=====================================

To convert WSDL and XML schemas (XSD files) to code, we use the wsdl2h command
on the command line (or command prompt), after opening a terminal.  The wsdl2h
command generates the data binding interface code that is saved to a special
Web services and data bindings interface header file with extension <i>`.h`</i>
that contains the WSDL service declarations and the data binding interface
declarations in a familiar C/C++ format:

    wsdl2h [options] -o file.h ... XSD and WSDL files ...

This command converts WSDL and XSD files to C++ (or pure C with
<b>`wsdl2h -c`</b>) and saves the data binding interface to a interface header
file <i>`file.h`</i> that uses familiar C/C++ syntax extended with `//gsoap`
[directives](#directives) and annotations.  Notational conventions are used in
the data binding interface to declare serializable C/C++ types and functions
for Web service operations.

The WSDL 1.1/2.0, SOAP 1.1/1.2, and XSD 1.0/1.1 standards are supported by the
gSOAP tools.  In addition, the most popular WS specifications are also
supported, including WS-Addressing, WS-ReliableMessaging, WS-Discovery,
WS-Security, WS-Policy, WS-SecurityPolicy, and WS-SecureConversation.

This article focusses mainly on XML data bindings.  XML data bindings for C/C++
bind XML schema types to C/C++ types.  So integers in XML are bound to C
integers, strings in XML are bound to C or C++ strings, complex types in XML
are bound to C structs or C++ classes, and so on.

A data binding is dual, meaning supporting a two way direction for development.
Either you start with WSDLs and/or XML schemas that are mapped to equivalent
C/C++ types, or you start with C/C++ types that are mapped to XSD types.
Either way, the end result is that you can serialize C/C++ types in XML such
that your XML is an instance of XML schema(s) and is validated against these
schema(s).

This covers all of the following standard XSD components with their optional
attributes and properties:

XSD component  | attributes and properties
-------------- | -------------------------
schema         | targetNamespace, version, elementFormDefault, attributeFormDefault, defaultAttributes
attribute      | name, ref, type, use, default, fixed, form, targetNamespace, wsdl:arrayType
element        | name, ref, type, default, fixed, form, nillable, abstract, substitutionGroup, minOccurs, maxOccurs, targetNamespace
simpleType     | name
complexType    | name, abstract, mixed, defaultAttributesApply
all            | *n/a*
choice         | minOccurs, maxOccurs
sequence       | minOccurs, maxOccurs
group          | name, ref, minOccurs, maxOccurs
attributeGroup | name, ref
any            | minOccurs, maxOccurs
anyAttribute   | *n/a*

And also the following standard XSD directives are covered:

directive  | description
---------- | -----------
import     | Imports a schema into the importing schema for referencing
include    | Include schema component definitions into a schema
override   | Override by replacing schema component definitions
redefine   | Extend or restrict schema component definitions
annotation | Annotates a component

The XSD facets and their mappings to C/C++ are:

XSD facet      | maps to
-------------- | -------
enumeration    | `enum`
simpleContent  | class/struct wrapper with `__item` member
complexContent | class/struct
list           | `enum*` bitmask (`enum*` enumerates a bitmask up to 64 bits)
extension      | class/struct inheritance/extension
restriction    | `typedef` and class/struct inheritance/redeclaration
length         | `typedef` with restricted content length annotation
minLength      | `typedef` with restricted content length annotation
maxLength      | `typedef` with restricted content length annotation
minInclusive   | `typedef` with numerical value range restriction annotation
maxInclusive   | `typedef` with numerical value range restriction annotation
minExclusive   | `typedef` with numerical value range restriction annotation
maxExclusive   | `typedef` with numerical value range restriction annotation
precision      | `typedef` with pattern annotation (pattern used for output, but input is not validated)
scale          | `typedef` with pattern annotation (pattern used for output, but input is not validated)
totalDigits    | `typedef` with pattern annotation (pattern used for output, but input is not validated)
fractionDigits | `typedef` with pattern annotation (pattern used for output, but input is not validated)
pattern        | `typedef` with pattern annotation (define `soap::fsvalidate` callback to validate patterns)
union          | string with union of value

All primitive XSD types are supported, including but not limited to the
following XSD types:

XSD type         | maps to
---------------- | -------
any/anyType      | `_XML` string with literal XML content (or enable DOM with wsdl2h option `-d`)
anyURI           | string (i.e. `char*`, `wchar_t*`, `std::string`, `std::wstring`)
string           | string (i.e. `char*`, `wchar_t*`, `std::string`, `std::wstring`)
boolean          | `bool` (C++) or `enum xsd__boolean` (C)
byte             | `char` (i.e. `int8_t`)
short            | `short` (i.e. `int16_t`)
int              | `int` (i.e. `int32_t`)
long             | `LONG64` (i.e. `long long` and `int64_t`)
unsignedByte     | `unsigned char` (i.e. `uint8_t`)
unsignedShort    | `unsigned short` (i.e. `uint16_t`)
unsignedInt      | `unsigned int` (i.e. `uint32_t`)
unsignedLong     | `ULONG64` (i.e. `unsigned long long` and `uint64_t`)
float            | `float`
double           | `double`
integer          | string or `#import "custom/int128.h"` to use 128 bit `xsd__integer`
decimal          | string or `#import "custom/long_double.h"` to use `long double`
precisionDecimal | string
duration         | string or `#import "custom/duration.h"` to use 64 bit `xsd__duration`
dateTime         | `time_t` or `#import "custom/struct_tm.h"` to use `struct tm` for `xsd__dateTime`
time             | string or `#import "custom/long_time.h"` to use 64 bit `xsd__time`
date             | string or `#import "custom/struct_tm_date.h"` to use `struct tm` for `xsd__date`
hexBinary        | special class/struct `xsd__hexBinary`
base64Binary     | special class/struct `xsd__base64Binary`
QName            | `_QName` string (URI normalization rules are applied)

All other primitive XSD types not listed above are mapped to strings, by
wsdl2h generating a `typedef` to string for these types.  For example,
<i>`xsd:token`</i> is bound to a C++ or C string:

~~~{.cpp}
    typedef std::string  xsd__token; // C++
    typedef char        *xsd__token; // C (wsdl2h option -c)
~~~

This associates a compatible value space to the type with the appropriate XSD
type name used by the soapcpp2-generated serializers.

It is possible to remap types by adding the appropriate mapping rules to
<i>`typemap.dat`</i> as we will explain in more detail in the next section.

Imported custom serializers are intended to extend the C/C++ type bindings when
the default binding to string is not satisfactory to your taste and if the
target platform supports these C/C++ types.  To add custom serializers to
<i>`typemap.dat`</i> for wsdl2h, see [adding custom serializers](#custom) below.

🔝 [Back to table of contents](#)

Using typemap.dat to customize data bindings                          {#typemap}
============================================

Use a <i>`typemap.dat`</i> file to redefine namespace prefixes and to customize type
bindings for the the generated header files produced by the wsdl2h tool.  The
<i>`typemap.dat`</i> is the default file processed by wsdl2h.  Use <b>`wsdl2h -tfile.dat`</b>
option <b>`-tfile.dat`</b> to specify a different mapping file <i>`file.dat`</i>.

Declarations in <i>`typemap.dat`</i> can be broken up over multiple lines by
continuing on the next line by ending each line to be continued with a
backslash <b>`\`</b>.  The limit is 4095 characters per line, whether the line is
broken up or not.

🔝 [Back to table of contents](#)

XML namespace bindings                                               {#typemap1}
----------------------

The wsdl2h tool generates C/C++ type declarations that use `ns1`, `ns2`, etc.
as schema-binding URI prefixes.  These default prefixes are generated somewhat
arbitrarily for each schema targetNamespace URI, meaning that their ordering
may change depending on the WSDL and XSD order of processing with wsdl2h.

Therefore, it is **strongly recommended** to declare your own prefix for each
schema URI in <i>`typemap.dat`</i> to reduce maintaince effort of your code.  This
is more robust when anticipating possible changes of the schema(s) and/or the
binding URI(s) and/or the tooling algorithms.

The first and foremost important thing to do is to define prefix-URI bindings
for our C/C++ code by adding the following line(s) to our <i>`typemap.dat`</i> or make
a copy of this file and add the line(s) that bind our choice of prefix name to
each URI:

    prefix = "URI"

For example, to use `g` as a prefix for the "urn:graph" XML namespace:

    g = "urn:graph"

This produces `g__name` C/C++ type names that are bound to the "urn:graph"
schema by association of `g` to the generated C/C++ types.

This means that <i>`<g:name xmlns:g="urn:graph">`</i> is parsed as an instance of a
`g__name` C/C++ type.  Also <i>`<x:name xmlns:x="urn:graph">`</i> parses as an
instance of `g__name`, because the prefix <i>`x`</i> has the same URI value
<i>`urn:graph`</i>.  Prefixes in XML have local scopes (like variables in a block).

The first run of wsdl2h will reveal the XML namespace URIs, so you do not need
to search WSDLs and XSD files for all of the target namespaces.  Just copy them
from the generated header file after the first run into <i>`typemap.dat`</i> for
editing.

@note Only define a namespace prefix once in <i>`typemap.dat`</i>.  That is, do not
use the same prefix for multiple XML namespace URIs.  This is to avoid
namespace conflicts that may cause failed builds and failures in XML parsing
and XML schema validation.

🔝 [Back to table of contents](#)

XSD type bindings                                                    {#typemap2}
-----------------

Custom C/C++ type bindings can be declared in <i>`typemap.dat`</i> to associate C/C++
types with specific schema types.  These type bindings have four parts:

    prefix__type = declaration | use | ptruse

where

- <b>`prefix__type`</b> is the schema type to be customized (the <b>`prefix__type`</b> name
  uses the common double underscore naming convention);

- <b>`declaration`</b> declares the C/C++ type in the wsdl2h-generated header file.
  This part can be empty if no explicit declaration is needed;

- <b>`use`</b> is an optional part that specifies how the C/C++ type is used in the
  code.  When omitted, it is the same as <b>`prefix__type`</b>;

- <b>`ptruse`</b> is an optional part that specifies how the type is used as a pointer
  type.  By default it is the <b>`use`</b> type name with a <b>`*`</b> or C++11
  <b>`std::shared_ptr<type>`</b> when enabled (see further below).  If <b>`use`</b> is already a
  pointer type by the presence of a <b>`*`</b> in the <b>`use`</b> part, then the default
  <b>`ptruse`</b> type is the same as the <b>`use`</b> type (that is, no double
  pointers <b>`**`</b> will be created in this case).

For example, to map <i>`xsd:duration`</i> to a `long long` (`LONG64`) type that holds
millisecond duration values, we can use the custom serializer declared in
<i>`gsoap/custom/duration.h`</i> by adding the following line to <i>`typemap.dat`</i>:

    xsd__duration = #import "custom/duration.h"

Here, we omitted the second and third parts, because `xsd__duration` is the
name that wsdl2h uses for this type in our generated code so we should leave
the <b>`use`</b> part unspecified.  The third part is omitted to let wsdl2h use
`xsd__duration *` for pointers or `std::shared_ptr<xsd__duration>` if smart
pointers are enabled.

To map <i>`xsd:string`</i> to `wchar_t*` wide strings for C source code output:

    xsd__string = | wchar_t* | wchar_t*

For C++ we can use the `std::wstring` wide string:

    xsd__string = | std::wstring

Note that the first part is empty, because these types do not require a
declaration.  A <b>`ptruse`</b> part is also defined for `wchar_t*`, but this
is actually needed because the wsdl2h tool recognizes that the <b>`use`</b>
part `wchar_t*` is already a pointer.  By contrast, when using 8-bit strings,
it is recommended to use the `SOAP_C_UTFSTRING` flag to enable UTF-8 formatted
strings.

When the auto-generated declaration should be preserved but the <b>`use`</b> or
<b>`ptruse`</b> parts replaced, then we use an ellipsis for the declaration part:

    prefix__type = ... | use | ptruse

This is useful to map schema polymorphic types to C types for example, where we
need to be able to both handle a base type and its extensions as per schema
extensibility.  Say we have a base type called <i>`ns:base`</i> that is extended, then
we can remap this to a C type that permits referening the extended types via a
`void*` as follows:

    ns__base = ... | int __type_base; void*

such that `__type_base` and `void*` will be used to (de)serialize any data
type, including base and its derived types.  The `__type_base` integer is set
to a `SOAP_TYPE_T` value to indicate what type of data the `void*` pointer
points to.

🔝 [Back to table of contents](#)

Custom serializers for XSD types                                       {#custom}
--------------------------------

In the previous part we saw how a custom serializer is used to bind
<i>`xsd:duration`</i> to a `long long` (`LONG64` or `int64_t`) type to store millisecond
duration values:

    xsd__duration = #import "custom/duration.h"

The `xsd__duration` type is an alias of `long long` (`LONG64` or `int64_t`).

While wsdl2h will use this binding declared in <i>`typemap.dat`</i>
automatically, you will also need to compile <i>`gsoap/custom/duration.c`</i>.
Each custom serializer has an interface header file to be imported into another
interface header file that declares the custom type for soapcpp2 and a
serializer implementation file written in C, which should be compiled with the
application.  You can compile these in C++ (rename files to <i>`.cpp`</i> if
needed).

A custom serializer is declared in an interface header file for soapcpp2 using
`extern typedef`.  The typedef name declared is serializable, whereas the
type on which it is based is not serializable.  This declaration can be
combined with `volatile` when the type should not be redeclared, see
[volatile classes and structs](#toxsd9-2).  For example, the custom serializer
for `struct tm` is the type `xsd__datetime` declared as follows in
`gsoap/custom/struct_tm.h`:

~~~{.cpp}
    extern typedef volatile struct tm
    {
        int   tm_sec;   ///< seconds (0 - 60)
        int   tm_min;   ///< minutes (0 - 59)
        int   tm_hour;  ///< hours (0 - 23)
        int   tm_mday;  ///< day of month (1 - 31)
        int   tm_mon;   ///< month of year (0 - 11)
        int   tm_year;  ///< year - 1900
        int   tm_wday;  ///< day of week (Sunday = 0) (NOT USED)
        int   tm_yday;  ///< day of year (0 - 365) (NOT USED)
        int   tm_isdst; ///< is summer time in effect?
        char* tm_zone;  ///< abbreviation of timezone (NOT USED)
    } xsd__dateTime;
~~~

Another example is `xsd__duration` as a custom serializer for the C++11 type
`std::chrono::nanoseconds`:

~~~{.cpp}
    extern typedef class std::chrono::nanoseconds xsd__duration;
~~~

Next, we present all pre-defined custom serializers that are available to you.

🔝 [Back to table of contents](#)

### xsd:integer                                                      {#custom-1}

The wsdl2h tool maps <i>`xsd:integer`</i> to a string by default.  To map <i>`xsd:integer`</i> to
the 128 bit big int type `__int128_t`:

    xsd__integer = #import "custom/int128.h"

The `xsd__integer` type is an alias of `__int128_t`.

@warning Beware that the <i>`xsd:integer`</i> value space of integers is in principle
unbounded and values can be of arbitrary length.  A value range fault
`SOAP_TYPE` (value exceeds native representation) or `SOAP_LENGTH` (value
exceeds range bounds) will be thrown by the deserializer if the value is out of
range.

Other XSD integer types that are restrictions of <i>`xsd:integer`</i>, are
<i>`xsd:nonNegativeInteger`</i> and <i>`xsd:nonPositiveInteger`</i>, which are further restricted
by <i>`xsd:positiveInteger`</i> and <i>`xsd:negativeInteger`</i>.  To bind these types to
`__int128_t` add the following definitions to <i>`typemap.dat`</i>:

    xsd__nonNegativeInteger = typedef xsd__integer xsd__nonNegativeInteger 0 :    ;
    xsd__nonPositiveInteger = typedef xsd__integer xsd__nonPositiveInteger   : 0  ;
    xsd__positiveInteger    = typedef xsd__integer xsd__positiveInteger    1 :    ;
    xsd__negativeInteger    = typedef xsd__integer xsd__negativeInteger      : -1 ;

Or simply uncomment these definitions in <i>`typemap.dat`</i> when you are using the
latest gSOAP releases.

@note If `__int128_t` 128 bit integers are not supported on your platform and if it
is certain that <i>`xsd:integer`</i> values are within 64 bit value bounds for your
application's use, then you can map this type to `LONG64`:

    xsd__integer = typedef LONG64 xsd__integer;

@note Again, a value range fault `SOAP_TYPE` or `SOAP_LENGTH` will be thrown by
the deserializer if the value is out of range.

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/int128.c`</i> with your project.

@see Section [numerical types](#toxsd5).

🔝 [Back to table of contents](#)

### xsd:decimal                                                      {#custom-2}

The wsdl2h tool maps <i>`xsd:decimal`</i> to a string by default.  To map <i>`xsd:decimal`</i> to
extended precision floating point:

    xsd__decimal = #import "custom/long_double.h" | long double

By contrast to all other custom serializers, this serializer enables `long
double` natively without requiring a new binding name (`xsd__decimal` is NOT
defined).

If your system supports <i>`quadmath.h`</i> quadruple precision floating point
`__float128`, you can map <i>`xsd:decimal`</i> to `xsd__decimal` that is an alias of
`__float128`:

    xsd__decimal = #import "custom/float128.h"

@warning Beware that <i>`xsd:decimal`</i> is in principle a decimal value with arbitraty
lengths.  A value range fault `SOAP_TYPE` will be thrown by the deserializer if
the value is out of range.

In the XML payload the special values <i>`INF`</i>, <i>`-INF`</i>, <i>`NaN`</i>
represent plus or minus infinity and not-a-number, respectively.

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/long_double.c`</i> with your
project.

@see Section [numerical types](#toxsd5).

🔝 [Back to table of contents](#)

### xsd:dateTime                                                     {#custom-3}

The wsdl2h tool maps <i>`xsd:dateTime`</i> to `time_t` by default.

The trouble with `time_t` when represented as 32 bit `long` integers is that it
is limited to dates between 1970 and 2038.  A 64 bit `time_t` is safe to use if
the target platform supports it, but lack of 64 bit `time_t` portability may
still cause date range issues.

For this reason `struct tm` should be used to represent wider date ranges.  This
custom serializer avoids using date and time information in `time_t`.  You get
the raw date and time information.  You only lose the day of the week
information.  It is always Sunday (`tm_wday=0`).

To map <i>`xsd:dateTime`</i> to `xsd__dateTime` which is an alias of `struct tm`:

    xsd__dateTime = #import "custom/struct_tm.h"

If the limited date range of `time_t` is not a problem but you want to increase
the time precision with fractional seconds, then we suggest to map <i>`xsd:dateTime`</i>
to `struct timeval`:

    xsd__dateTime = #import "custom/struct_timeval.h"

If the limited date range of `time_t` is not a problem but you want to use the
C++11 time point type `std::chrono::system_clock::time_point` (which internally
uses `time_t`):

    xsd__dateTime = #import "custom/chrono_time_point.h"

Again, we should make sure that the dates will not exceed the date range when
using the default `time_t` binding for <i>`xsd:dateTime`</i> or when binding
<i>`xsd:dateTime`</i> to `struct timeval` or to `std::chrono::system_clock::time_point`.
These are safe to use in applications that use <i>`xsd:dateTime`</i> to record date
stamps within a given window.  Otherwise, we recommend the `struct tm` custom
serializer.

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/struct_tm.c`</i> with your
project.

You could even map <i>`xsd:dateTime`</i> to a plain string (use `char*` with C and
`std::string` with C++).  For example:

    xsd__dateTime = | char*

@see Section [date and time types](#toxsd7).

🔝 [Back to table of contents](#)

### xsd:date                                                         {#custom-4}

The wsdl2h tool maps <i>`xsd:date`</i> to a string by default.  We can map <i>`xsd:date`</i> to
`struct tm`:

    xsd__date = #import "custom/struct_tm_date.h"

The `xsd__date` type is an alias of `struct tm`.  The serializer ignores the
time part and the deserializer only populates the date part of the struct,
setting the time to 00:00:00.  There is no unreasonable limit on the date range
because the year field is stored as an integer (`int`).

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/struct_tm_date.c`</i> with your
project.

@see Section [date and time types](#toxsd7).

🔝 [Back to table of contents](#)

### xsd:time                                                         {#custom-5}

The wsdl2h tool maps <i>`xsd:time`</i> to a string by default.  We can map <i>`xsd:time`</i> to
an `unsigned long long` (`ULONG64` or `uint64_t`) integer with microsecond time
precision:

    xsd__time = #import "custom/long_time.h"

This type represents 00:00:00.000000 to 23:59:59.999999, from `0` to an upper
bound of `86399999999`.  A microsecond resolution means that a 1 second
increment requires an increment of 1000000 in the integer value.  The serializer
adds a UTC time zone.

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/long_time.c`</i> with your
project.

@see Section [date and time types](#toxsd7).

🔝 [Back to table of contents](#)

### xsd:duration                                                     {#custom-6}

The wsdl2h tool maps <i>`xsd:duration`</i> to a string by default, unless <i>`xsd:duration`</i>
is mapped to a `long long` (`LONG64` or `int64_t`) type with with millisecond
(ms) time duration precision:

    xsd__duration = #import "custom/duration.h"

The `xsd__duration` type is a 64 bit signed integer that can represent
106,751,991,167 days forwards (positive) and backwards (negative) in time in
increments of 1 ms (1/1000 of a second).

Rescaling of the duration value by may be needed when adding the duration value
to a `time_t` value, because `time_t` may or may not have a seconds resolution,
depending on the platform and possible changes to `time_t`.

Rescaling is done automatically when you add a C++11 `std::chrono::nanoseconds`
value to a `std::chrono::system_clock::time_point` value.  To use
`std::chrono::nanoseconds` as <i>`xsd:duration`</i>:

    xsd__duration = #import "custom/chrono_duration.h"

This type can represent 384,307,168 days (2^63 nanoseconds) forwards and
backwards in time in increments of 1 ns (1/1,000,000,000 of a second).

Certain observations with respect to receiving durations in years and months
apply to both of these serializer decoders for <i>`xsd:duration`</i>.

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/duration.c`</i> with your
project.

@see Section [time duration types](#toxsd8).

🔝 [Back to table of contents](#)

Custom Qt serializers for XSD types                                        {#qt}
-----------------------------------

The gSOAP distribution includes several custom serializers for Qt types.  Also
Qt container classes are supported, see
[the built-in typemap.dat variables $CONTAINER, $POINTER and $SIZE](#typemap5).

This feature requires gSOAP 2.8.34 or higher and Qt 4.8 or higher.

Each Qt custom serializer has an interface header file for soapcpp2 and a C++
implementation file to be compiled with your project.

Other Qt primitive types that are Qt `typedef`s of C/C++ types do not require a
custom serializer.

🔝 [Back to table of contents](#)

### xsd:string                                                           {#qt-1}

To use Qt strings instead of C++ strings, add the following definition to
<i>`typemap.dat`</i>:

    xsd__string = #import "custom/qstring.h"

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/qstring.cpp`</i> with your
project.

🔝 [Back to table of contents](#)

### xsd:base64Binary                                                     {#qt-2}

To use Qt byte arrays for <i>`xsd:base64Binary`</i> instead of the
`xsd__base64Binary` class, add the following definition to <i>`typemap.dat`</i>:

    xsd__base64Binary = #import "custom/qbytearray_base64.h"

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/qbytearray_base64.cpp`</i> with
your project.

🔝 [Back to table of contents](#)

### xsd:hexBinary                                                        {#qt-3}

To use Qt byte arrays for <i>`xsd:hexBinary`</i> instead of the `xsd__base64Binary`
class, add the following definition to <i>`typemap.dat`</i>:

    xsd__hexBinary = #import "custom/qbytearray_hex.h"

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/qbytearray_hex.cpp`</i> with
your project.

🔝 [Back to table of contents](#)

### xsd:dateTime                                                         {#qt-4}

To use Qt QDateTime for <i>`xsd:dateTime`</i>, add the following definition to
<i>`typemap.dat`</i>:

    xsd__dateTime = #import "custom/datetime.h"

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/qdatetime.cpp`</i> with
your project.

🔝 [Back to table of contents](#)

### xsd:date                                                             {#qt-5}

To use Qt QDate for <i>`xsd:date`</i>, add the following definition to
<i>`typemap.dat`</i>:

    xsd__date = #import "custom/qdate.h"

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/qdate.cpp`</i> with your
project.

🔝 [Back to table of contents](#)

### xsd:time                                                             {#qt-6}

To use Qt QDate for <i>`xsd:time`</i>, add the following definition to
<i>`typemap.dat`</i>:

    xsd__time = #import "custom/qtime.h"

After running wsdl2h and soapcpp2, compile <i>`gsoap/custom/qtime.cpp`</i> with your
project.

🔝 [Back to table of contents](#)

Class/struct member additions                                        {#typemap3}
-----------------------------

All generated classes and structs can be augmented with additional
members such as methods, constructors and destructors, and private members:

    prefix__type = $ member-declaration

For example, we can add method declarations and private members to a class, say
`ns__record` as follows:

    ns__record = $ ns__record(const ns__record &); // copy constructor
    ns__record = $ void print();                   // a print method
    ns__record = $ private: int status;            // a private member

Method declarations cannot include any code, because soapcpp2's input permits
only type declarations, not code.

🔝 [Back to table of contents](#)

Replacing XSD types by equivalent alternatives                       {#typemap4}
----------------------------------------------

Type replacements can be given to replace one type entirely with another given
type:

    prefix__type1 == prefix__type2

This replaces all `prefix__type1` by `prefix__type2` in the wsdl2h output.

@warning Do not agressively replace types, because this can cause XML schema
validation to fail when a value-type mismatch is encountered in the XML input.
Therefore, only replace similar types with other similar types that are wider
(e.g.  `short` by `int` and `float` by `double`).

🔝 [Back to table of contents](#)

The built-in typemap.dat variables $CONTAINER, $POINTER and $SIZE    {#typemap5}
-----------------------------------------------------------------

The <i>`typemap.dat`</i> <b>`$CONTAINER`</b> variable defines the container type to use in
the wsdl2h-generated declarations for C++, which is `std::vector` by default.
For example, to use `std::list` as the container in the wsdl2h-generated
declarations we add the following line to <i>`typemap.dat`</i>:

    $CONTAINER = std::list

Also a Qt container can be used instead of the default `std::vector`, for
example `QVector`:

    [
    #include <QVector>
    ]
    $CONTAINER = QVector

To remove containers, use <b>`wsdl2h -s`</b>.  This also removes `std::string`,
but you can re-introduce `std::string` with
<b>`xsd__string = | std::string`</b> in <i>`typemap.dat`</i>.

The <i>`typemap.dat`</i> <b>`$POINTER`</b> variable defines the smart pointer to use in the
wsdl2h-generated declarations for C++, which replaces the use of `*` pointers.
For example:

    $POINTER = std::shared_ptr

Not all pointers in the generated output are replaced by smart pointers by
wsdl2h, such as pointers as union members and pointers as struct/class members
that point to arrays of values.

@note The standard smart pointer `std::shared_ptr` is generally safe to use.
Other smart pointers such as `std::unique_ptr` and `std::auto_ptr` may cause
compile-time errors when classes have smart pointer members but no copy
constructor (a default copy constructor).  A copy constructor is required for
non-shared smart pointer copying or swapping.

Alternatives to `std::shared_ptr` of the form `NAMESPACE::shared_ptr` can be
assigned to <b>`$POINTER`</b> when the namespace `NAMESPACE` also implements
`NAMESPACE::make_shared` and when the shared pointer class provides `reset()`
and`get()` methods and the dereference operator.  For example Boost
`boost::shared_ptr`:

    [
    #include <boost/shared_ptr.hpp>
    ]
    $POINTER = boost::shared_ptr

The user-defined content between <b>`[`</b> and <b>`]`</b> ensures that we include the Boost
header files that are needed to support `boost::shared_ptr` and
`boost::make_shared`.

The variable <b>`$SIZE`</b> defines the type of array sizes, which is `int` by
default.  For example, to change array size types to `size_t`:

    $SIZE = size_t

Permissible types are `int` and `size_t`.  This variable does not affect the
size of dynamic arrays, `xsd__hexBinary` and `xsd__base64Binary` types, which
is always `int`.

🔝 [Back to table of contents](#)

User-defined content                                                 {#typemap6}
--------------------

Any other content to be generated by wsdl2h can be included in <i>`typemap.dat`</i> by
enclosing it within brackets <b>`[`</b> and <b>`]`</b> anywhere in the <i>`typemap.dat`</i> file.
Each of the two brackets must appear at the start of a new line.

For example, we can add an `#import "wsa5.h"` to the wsdl2h-generated output as
follows:

    [
    #import "import/wsa5.h"
    ]

which emits the `#import "import/wsa5.h"` literally at the start of the
wsdl2h-generated header file.

🔝 [Back to table of contents](#)

Mapping C/C++ to XML schema                                             {#toxsd}
===========================

The soapcpp2 command generates the data binding implementation code from a data
binding interface <i>`file.h`</i>:

    soapcpp2 [options] file.h

where <i>`file.h`</i> is a interface header file that declares the XML data
binding interface.  The <i>`file.h`</i> is typically generated by wsdl2h, but
you can also declare one yourself.  If so, add `//gsoap`
[directives](#directives) and declare in this file all our C/C++ types you want
to serialize in XML.

You can also declare functions that will be converted to Web service operations
by soapcpp2.  Global function declarations define service operations, which are
of the form:

~~~{.cpp}
    int prefix__func(arg1, arg2, ..., argn, result);
~~~

where `arg1`, `arg2`, ..., `argn` are formal argument declarations of the input
and `result` is a formal argument for the output, which must be a pointer or
reference to the result object to be populated.  More information on declaring
and implementing service operation functions can be found in the
[gSOAP user guide.](../../guide/html/index.html)

🔝 [Back to table of contents](#)

Overview of serializable C/C++ types                                   {#toxsd1}
------------------------------------

The following C/C++ types are supported by soapcpp2 and mapped to XSD types
and constructs.  See the subsections below for more details or follow the links.

🔝 [Back to table of contents](#)

### List of Boolean types

Boolean Type                  | Notes
----------------------------- | -----
`bool`                        | C++ bool
`enum xsd__boolean`           | C alternative to C++ `bool` with `false_` and `true_`
 
@see Section [C++ bool and C alternative](#toxsd3).

🔝 [Back to table of contents](#)

### List of enumeration and bitmask types

Enumeration Type              | Notes
----------------------------- | -----
`enum`                        | enumeration
`enum class`                  | C++11 scoped enumeration, requires `soapcpp2 -c++11`
`enum*`                       | a bitmask that enumerates values 1, 2, 4, 8, ...
`enum* class`                 | C++11 scoped enumeration bitmask, requires `soapcpp2 -c++11`

@see Section [enumerations and bitmasks](#toxsd4).

🔝 [Back to table of contents](#)

### List of numerical types

Numerical Type                | Notes
----------------------------- | -----
`char`                        | byte
`short`                       | 16 bit integer
`int`                         | 32 bit integer
`long`                        | 32 bit integer
`LONG64`                      | 64 bit integer
`xsd__integer`                | 128 bit integer, use `#import "custom/int128.h"`
`long long`                   | same as `LONG64`
`unsigned char`               | unsigned byte
`unsigned short`              | unsigned 16 bit integer
`unsigned int`                | unsigned 32 bit integer
`unsigned long`               | unsigned 32 bit integer
`ULONG64`                     | unsigned 64 bit integer
`unsigned long long`          | same as `ULONG64`
`int8_t`                      | same as `char`
`int16_t`                     | same as `short`
`int32_t`                     | same as `int`
`int64_t`                     | same as `LONG64`
`uint8_t`                     | same as `unsigned char`
`uint16_t`                    | same as `unsigned short`
`uint32_t`                    | same as `unsigned int`
`uint64_t`                    | same as `ULONG64`
`size_t`                      | transient type (not serializable)
`float`                       | 32 bit float
`double`                      | 64 bit float
`long double`                 | extended precision float, use `#import "custom/long_double.h"`
`xsd__decimal`                | `quadmath.h` library 128 bit quadruple precision float, use `#import "custom/float128.h"`
`typedef`                     | declares a type name, with optional value range and string length bounds

@see Section [numerical types](#toxsd5).

🔝 [Back to table of contents](#)

### List of string types

String Type                   | Notes
----------------------------- | -----
`char*`                       | string (may contain UTF-8 with flag `SOAP_C_UTFSTRING`)
`wchar_t*`                    | wide string
`std::string`                 | C++ string (may contain UTF-8 with flag `SOAP_C_UTFSTRING`)
`std::wstring`                | C++ wide string
`char[N]`                     | fixed-size string, requires `soapcpp2 -b`
`_QName`                      | normalized QName content
`_XML`                        | literal XML string content with wide characters in UTF-8
`typedef`                     | declares a new string type name, may restrict string length

@see Section [string types](#toxsd6).

🔝 [Back to table of contents](#)

### List of date and time types

Date and Time Type                      | Notes
--------------------------------------- | -----
`time_t`                                | date and time point since epoch
`struct tm`                             | date and time point, use `#import "custom/struct_tm.h"`
`struct tm`                             | date point, use `#import "custom/struct_tm_date.h"`
`struct timeval`                        | date and time point, use `#import "custom/struct_timeval.h"`
`unsigned long long`                    | time point in microseconds, use `#import "custom/long_time.h"`
`std::chrono::system_clock::time_point` | date and time point, use `#import "custom/chrono_time_point.h"`

@see Section [date and time types](#toxsd7).

🔝 [Back to table of contents](#)

### List of time duration types

Time Duration Type            | Notes
----------------------------- | -----
`long long`                   | duration in milliseconds, use `#import "custom/duration.h"`
`std::chrono::nanoseconds`    | duration in nanoseconds, use `#import "custom/chrono_duration.h"`

@see Section [time duration types](#toxsd8).

🔝 [Back to table of contents](#)

### List of classes, structs, unions, pointers, containers, and arrays

Classes, Structs, and Members | Notes
----------------------------- | -----
`class`                       | C++ class with single inheritance only
`struct`                      | C struct or C++ struct without inheritance
`std::shared_ptr<T>`          | C++11 smart shared pointer
`std::unique_ptr<T>`          | C++11 smart pointer
`std::auto_ptr<T>`            | C++ smart pointer
`std::deque<T>`               | use `#import "import/stldeque.h"`
`std::list<T>`                | use `#import "import/stllist.h"`
`std::vector<T>`              | use `#import "import/stlvector.h"`
`std::set<T>`                 | use `#import "import/stlset.h"`
`template<T> class`           | a container with `begin()`, `end()`, `size()`, `clear()`, and `insert()` methods
`T*`                          | pointer to data of type `T`
`T*`                          | as a class or struct member: points to data of type `T` or array of `T` with member `__size`
`T[N]`                        | as a class or struct member: fixed-size array of type `T`
`union`                       | as a class or struct member: requires a variant selector member `__union`
`void*`                       | as a class or struct member: requires a `__type` member to indicate the type of object pointed to

@see Section [classes and structs](#toxsd9).

🔝 [Back to table of contents](#)

### List of special classes and structs

Special Classes and Structs   | Notes
----------------------------- | -----
Special Array class/struct    | single and multidimensional SOAP Arrays
Special Wrapper class/struct  | complexTypes with simpleContent, wraps `__item` member
`xsd__hexBinary`              | binary content
`xsd__base64Binary`           | binary content and optional DIME/MIME/MTOM attachments
`xsd__anyType`                | DOM elements, use `#import "dom.h"`
`@xsd__anyAttribute`          | DOM attributes, use `#import "dom.h"`

@see Section [special classes and structs](#toxsd10).

🔝 [Back to table of contents](#)

Colon notation versus name prefixing with XML tag name translation     {#toxsd2}
------------------------------------------------------------------

To bind C/C++ type names to XSD types, a simple form of name prefixing is used
by the gSOAP tools by prepending the XML namespace prefix to the C/C++ type
name with a pair of undescrores.  This also ensures that name clashes cannot
occur when multiple WSDL and XSD files are converted to C/C++.  Also, C++
namespaces are not sufficiently rich to capture XML schema namespaces
accurately, for example when class members are associated with schema elements
defined in another XML namespace and thus the XML namespace scope of the
member's name is relevant, not just its type.

However, from a C/C++ centric point of view this can be cumbersome.  Therefore,
colon notation is an alternative to physically augmenting C/C++ names with
prefixes.

For example, the following class uses colon notation to bind the `record` class
to the <i>`urn:types`</i> schema:

~~~{.cpp}
    //gsoap ns schema namespace: urn:types
    class ns:record        // binding 'ns:' to a type name
    { public:
        std::string name;
        uint64_t    SSN;
        ns:record   *spouse; // using 'ns:' with the type name
        ns:record();         // using 'ns:' here too
        ~ns:record();        // and here
    };
~~~

The colon notation is stripped away by soapcpp2 when generating the data
binding implementation code for our project.  So the final code just uses
`record` to identify this class and its constructor/destructor.

When using colon notation make sure to be consistent and not use colon notation
mixed with prefixed forms.  The qualified name `ns:record` differs from `ns__record`,
because `ns:record` is compiled to an unqualified `record` name in the source
code output by the soapcpp2 tool.

Colon notation also facilitates overruling the elementFormDefault and
attributeFormDefault declaration that is applied to local elements and
attributes, when declared as members of classes, structs, and unions.  For more
details, see [qualified and unqualified members](#toxsd9-6).

A C/C++ identifier name (a type name, member name, function name, or parameter
name) is translated to an XML tag name by the following rules:

- Two leading underscores indicates that the identifier name has no XML tag
  name, i.e. this name is not visible in XML and is not translated.

- A leading underscore is removed, but the underscore indicates that: **a**) a
  struct/class member name or parameter name has a wildcard XML tag name (i.e.
  matches any XML tag), or **b**) a type name that has a
  [document root element definition](#toxsd9-7).

- Trailing underscores are removed (i.e. trailing underscores can be used to
  avoid name clashes with keywords).

- Underscores within names are translated to hyphens (hyphens are more common
  in XML tag names).

- `_USCORE` is translated to an underscore in the translated XML tag name.

- `_DOT` is translated to a dot (<i>`.`</i>) in the translated XML tag name.

- `_xHHHH` is translated to the Unicode character with code point HHHH (hex).

- C++11 Unicode identifier name characters in UTF-8 are translated as-is.

For example, the C/C++ namespace qualified identifier name `s_a__my_way` is
translated to the XML tag name <i>`s-a:my-way`</i> by translating the prefix `s_a`
and the local name `my_way`.

Struct/class member and parameter name translation can be overruled by using
[backtick XML tags](#toxsd9-5-1) (with gSOAP 2.8.30 and greater).

🔝 [Back to table of contents](#)

C++ bool and C alternative                                             {#toxsd3}
-------------------------- 

The C++ `bool` type is bound to built-in XSD type <i>`xsd:boolean`</i>.

The C alternative is to define an enumeration:

~~~{.cpp}
    enum xsd__boolean { false_, true_ };
~~~

or by defining an enumeration in C with pseudo-scoped enumeration constants:

~~~{.cpp}
    enum xsd__boolean { xsd__boolean__false, xsd__boolean__true };
~~~

The XML value space of these types is <i>`false`</i> and <i>`true`</i>, but also accepted
are <i>`0`</i> and <i>`1`</i> values for <i>`false`</i> and <i>`true`</i>, respectively.

To prevent name clashes, `false_` and `true_` have a trailing underscore in
their `enum` symbols.  Trailing underscores are removed from the XML value space.

🔝 [Back to table of contents](#)

Enumerations and bitmasks                                              {#toxsd4}
-------------------------

Enumerations are mapped to XSD simpleType enumeration restrictions of
<i>`xsd:string`</i>, <i>`xsd:QName`</i>, and <i>`xsd:long`</i>.

Consider for example:

~~~{.cpp}
    enum ns__Color { RED, WHITE, BLUE };
~~~

which maps to a simpleType restriction of <i>`xsd:string`</i> in the soapcpp2-generated
schema:

<div class="alt">
~~~{.xml}
    <simpleType name="Color">
      <restriction base="xsd:string">
        <enumeration value="RED"/>
        <enumeration value="WHITE"/>
        <enumeration value="BLUE"/>
      </restriction>
    </simpleType>
~~~
</div>

Enumeration name constants can be pseudo-scoped to prevent name clashes,
because enumeration name constants have a global scope in C and C++:

~~~{.cpp}
    enum ns__Color { ns__Color__RED, ns__Color__WHITE, ns__Color__BLUE };
~~~

You can also use C++11 scoped enumerations to prevent name clashes:

~~~{.cpp}
    enum class ns__Color : int { RED, WHITE, BLUE };
~~~

Here, the enumeration class base type `: int` is optional.  In place of `int`
in the example above, we can also use `int8_t`, `int16_t`, `int32_t`, or
`int64_t`.

The XML value space of the enumertions defined above is <i>`RED`</i>, <i>`WHITE`</i>, and
<i>`BLUE`</i>.

Prefix-qualified enumeration name constants are mapped to simpleType
restrictions of <i>`xsd:QName`</i>, for example:

~~~{.cpp}
    enum ns__types { xsd__int, xsd__float };
~~~

which maps to a simpleType restriction of <i>`xsd:QName`</i> in the soapcpp2-generated
schema:

<div class="alt">
~~~{.xml}
    <simpleType name="types">
      <restriction base="xsd:QName">
        <enumeration value="xsd:int"/>
        <enumeration value="xsd:float"/>
      </restriction>
    </simpleType>
~~~
</div>

Enumeration name constants can be pseudo-numeric as follows:

~~~{.cpp}
    enum ns__Primes { _3 = 3, _5 = 5, _7 = 7, _11 = 11 };
~~~

which maps to a simpleType restriction of <i>`xsd:long`</i>:

<div class="alt">
~~~{.xml}
    <simpleType name="Color">
      <restriction base="xsd:long">
        <enumeration value="3"/>
        <enumeration value="5"/>
        <enumeration value="7"/>
        <enumeration value="11"/>
      </restriction>
    </simpleType>
~~~
</div>

The XML value space of this type is <i>`3`</i>, <i>`5`</i>, <i>`7`</i>, and <i>`11`</i>.

Besides (pseudo-) scoped enumerations, another way to prevent name clashes
accross enumerations is to start an enumeration name constant with one
underscore or followed it by any number of underscores, which makes it
unique.  The leading and trailing underscores are removed from the XML value
space.

~~~{.cpp}
    enum ns__ABC { A, B, C };
    enum ns__BA  { B, A };    // BAD: B = 1 but B is already defined as 2
    enum ns__BA_ { B_, A_ };  // OK
~~~

The gSOAP soapcpp2 tool permits reusing enumeration name constants across
(non-scoped) enumerations as long as these values are assigned the same
constant.  Therefore, the following is permitted:

~~~{.cpp}
    enum ns__Primes { _3 = 3, _5 = 5, _7 = 7, _11 = 11 };
    enum ns__Throws { _1 = 1, _2 = 2, _3 = 3, _4 = 4, _5 = 5, _6 = 6 };
~~~

A bitmask type is an `enum*` "product enumeration" with a geometric,
power-of-two sequence of values assigned to the enumeration constants:

~~~{.cpp}
    enum* ns__Options { SSL3, TLS10, TLS11, TLS12, TLS13 };
~~~

where the product enum assigns 1 to `SSL3`, 2 to `TLS10`, 4 to `TLS11`, 8
to `TLS12`, and 16 to `TLS13`, which allows these enumeration constants to be
used in composing bitmasks with `|` (bitwise or) `&` (bitwise and), and `~`
(bitwise not):

~~~{.cpp}
    enum ns__Options options = (enum ns__Options)(SSL3 | TLS10 | TLS11 | TLS12 | TLS13);
    if (options & SSL3) // if SSL3 is an option, warn and remove from options
    {
      warning();
      options &= ~SSL3;
    }
~~~

The bitmask type maps to a simpleType list restriction of <i>`xsd:string`</i> in the
soapcpp2-generated XML schema:

<div class="alt">
~~~{.xml}
    <simpleType name="Options">
      <list>
        <restriction base="xsd:string">
          <enumeration value="SSL3"/>
          <enumeration value="TLS10"/>
          <enumeration value="TLS11"/>
          <enumeration value="TLS12"/>
          <enumeration value="TLS13"/>
        </restriction>
      </list>
    </simpleType>
~~~
</div>

The XML value space of this type consists of all 16 possible subsets of the
four values, represented by an XML string with space-separated values.  For
example, the bitmask `TLS10 | TLS11 | TLS12` equals 14 and is represented by
the XML text <i>`TLS10 TLS11 TLS12`</i>.

You can also use C++11 scoped enumerations with bitmasks using `enum*` product
enumerations:

~~~{.cpp}
    enum* class ns__Options { SSL3, TLS10, TLS11, TLS12, TLS13 };
~~~

The base type of a scoped enumeration bitmask, when explicitly given, is
ignored.  The base type is either `int` or `int64_t`, depending on the number
of constants enumerated in the bitmask.

To convert `enum` name constants and bitmasks to a string, we use the
auto-generated function for enum `T`:

~~~{.cpp}
    const char *soap_T2s(struct soap*, enum T val)
~~~

The string returned is stored in an internal buffer of the current `soap`
context, so you should copy it to keep it from being overwritten.  For example,
use `char *soap_strdup(struct soap*, const char*)`.

To convert a string to an `enum` constant or bitmask, we use the auto-generated
function

~~~{.cpp}
    int soap_s2T(struct soap*, const char *str, enum T *val)
~~~
  
This function takes the name (or names, space-separated for bitmasks) of
the enumeration constant in a string `str`.  Names should be given without the
pseudo-scope prefix and without trailing underscores.  The function sets `val`
to the corresponding integer enum constant or to a bitmask.  The function
returns `SOAP_OK` (zero) on success or an error if the string is not a valid
enumeration name.

🔝 [Back to table of contents](#)

Numerical types                                                        {#toxsd5}
---------------

Integer and floating point types are mapped to the equivalent built-in XSD
types with the same sign and bit width.

The `size_t` type is transient (not serializable) because its width is platform
dependent.  We recommend to use `uint64_t` instead.

The XML value space of integer types are their decimal representations without
loss of precision.

The XML value space of floating point types are their decimal representations.
The decimal representations are formatted with the printf format string `"%.9G"`
for floats and the printf format string `"%.17lG"` for double.  To change the
format strings, we can assign new strings to the following `soap` context
members:

~~~{.cpp}
    soap.float_format       = "%g";
    soap.double_format      = "%lg";
    soap.long_double_format = "%Lg";
~~~

Decimal representations may result in a loss of precision of the least
significant decimal.  Therefore, the format strings that are used by default
are sufficiently precise to avoid loss, but this may result in long decimal
fractions in the XML value space.

The `long double` extended floating point type requires a custom serializer:

~~~{.cpp}
    #import "custom/long_double.h"
    ... // use long double
~~~

You can now use `long double`, which has a serializer that serializes this type
as <i>`xsd:decimal`</i>.  Compile and link your code with the file
<i>`gsoap/custom/long_double.c`</i>.

The value space of floating point values includes the special values
<i>`INF`</i>, <i>`-INF`</i>, and <i>`NaN`</i>.  You can check a value for plus
or minus infinity and not-a-number as follows:

~~~{.cpp}
    soap_isinf(x) && x > 0 // is x INF?
    soap_isinf(x) && x < 0 // is x -INF?
    soap_isnan(x)          // is x NaN?
~~~

To assign these values, use:

~~~{.cpp}
    // x is float       // x is double, long double, or __float128
    x = FLT_PINFY;      x = DBL_PINFTY;
    x = FLT_NINFY;      x = DBL_NINFTY;
    x = FLT_NAN;        x = DBL_NAN;
~~~

If your system supports `__float128` then you can also use this 128 bit
floating point type with a custom serializer:

~~~{.cpp}
    #import "custom/float128.h"
    ... // use xsd__decimal
~~~

Then use the `xsd__decimal` alias of `__float128`, which has a serializer.  Do
not use `__float128` directly, which is transient (not serializable).

To check for <i>`INF`</i>, <i>`-INF`</i>, and <i>`NaN`</i> of a `__float128`
value use:

~~~{.cpp}
    isinfq(x) && x > 0 // is x INF?
    isinfq(x) && x < 0 // is x -INF?
    isnanq(x)          // is x NaN?
~~~

The range of a `typedef`-defined numerical type can be restricted using the range
`:` operator with inclusive lower and upper bounds.  For example:

~~~{.cpp}
    typedef int ns__narrow -10 : 10;
~~~

This maps to a simpleType restriction of <i>`xsd:int`</i> in the soapcpp2-generated
schema:

<div class="alt">
~~~{.xml}
    <simpleType name="narrow">
      <restriction base="xsd:int">
        <minInclusive value="-10"/>
        <maxInclusive value="10"/>
      </restriction>
    </simpleType>
~~~
</div>

The lower and upper bound of a range are optional.  When omitted, values are
not bound from below or from above, respectively.

The range of a floating point `typedef`-defined type can be restricted within
floating point constant bounds.

Also with a floating point `typedef` a `printf`-format pattern can be given of the
form `"%[width][.precision]f"` to format decimal values using the given width
and precision fields:

~~~{.cpp}
    typedef float ns__PH "%5.2f" 0.0 : 14.0;
~~~

This maps to a simpleType restriction of <i>`xsd:float`</i> in the soapcpp2-generated
schema:

<div class="alt">
~~~{.xml}
    <simpleType name="PH">
      <restriction base="xsd:float">
        <totalDigits value="5"/>
        <fractionDigits value="2"/>
        <minInclusive value="0"/>
        <maxInclusive value="14"/>
      </restriction>
    </simpleType>
~~~
</div>

For exclusive bounds, we use the `<` operator instead of the `:` range
operator:

~~~{.cpp}
    typedef float ns__epsilon 0.0 < 1.0;
~~~

Values `eps` of `ns__epsilon` are restricted between `0.0 < eps < 1.0`.

This maps to a simpleType restriction of <i>`xsd:float`</i> in the soapcpp2-generated
schema: