Genivia Home Documentation
README.md Source File

updated Tue Jul 11 2017 by Robert van Engelen
 
README.md
Go to the documentation of this file.
1 
2 C and C++ XML Data Bindings {#mainpage}
3 ===========================
4 
5 [TOC]
6 
7 Introduction {#intro}
8 ============
9 
10 This article gives a detailed overview of the gSOAP C and C++ XML data bindings
11 and highlights the advantages, concepts, usage, and implementation aspects of
12 XML data bindings.
13 
14 The major advantage of XML data bindings is that your application data is
15 always **type safe** in C and C++ by binding XML schema types to C/C++ types.
16 So integers in XML are bound to C integers, strings in XML are bound to C or
17 C++ strings, complex types in XML are bound to C structs or C++ classes, and so
18 on. The structured data you create and accept will fit the data model and is
19 **static type safe**. In other words, by leveraging strong typing in C/C++,
20 your XML data meets **XML schema validation requirements** and satisfies **XML
21 interoperability requirements**.
22 
23 The gSOAP data bindings are more powerful than simply representing C/C++ data
24 in XML. In fact, the tools implement **true serialization** of C/C++ data in
25 XML, including the serialization of cyclic graph structures. The gSOAP tools
26 also generate routines for deep copying and deep deletion of C/C++ data
27 structures to simplify memory management. In addition, C/C++ structures are
28 deserialized into managed memory, managed by the gSOAP `soap` context.
29 
30 At the end of this document two examples are given to illustrate the
31 application of XML data bindings. The first simple example `address.cpp` shows
32 how to use wsdl2h to bind an XML schema to C++. The C++ application reads and
33 writes an XML file into and from a C++ "address book" data structure. The C++
34 data structure is an STL vector of address objects. The second example
35 `graph.cpp` shows how C++ data can be accurately serialized as a tree, digraph,
36 and cyclic graph in XML. The digraph and cyclic graph serialization rules
37 implement SOAP 1.1/1.2 multi-ref encoding with id-ref attributes to link
38 elements through IDREF XML references, creating a an XML graph with pointers to
39 XML nodes that preserves the structural integrity of the serialized C++ data.
40 
41 These examples demonstrate XML data bindings only for relatively simple data
42 structures and types. The gSOAP tools support more than just these type of
43 structures to serialize in XML. There are practically no limits to
44 enable XML serialization of C and C++ types.
45 
46 Support for XML schema components is unlimited. The wsdl2h tool maps schemas
47 to C and C++ using built-in intuitive mapping rules, while allowing the
48 mappings to be customized using a `typemap.dat` file with mapping instructions
49 for wsdl2h.
50 
51 The information in this document is applicable to gSOAP 2.8.26 and later
52 versions that support C++11 features. However, C++11 is not required to use
53 this material and the examples included, unless we need smart pointers and
54 scoped enumerations. While most of the examples in this document are given in
55 C++, the concepts also apply to C with the exception of containers, smart
56 pointers, classes and their methods. None of these exceptions limit the use of
57 the gSOAP tools for C in any way.
58 
59 The data binding concepts described in this document were first envisioned in
60 1999 by Prof. Robert van Engelen at the Florida State University. An
61 implementation was created in 2000, named "stub/skeleton compiler". The first
62 articles on its successor version "gSOAP" appeared in 2002. The principle of
63 mapping XSD components to C/C++ types and vice versa is now widely adopted in
64 systems and programming languages, including Java web services and by C# WCF.
65 
66 We continue to be committed to our goal to empower C/C++ developers with
67 powerful autocoding tools for XML. Our commitment started in the very early
68 days of SOAP by actively participating in
69 [SOAP interoperability testing](http://www.whitemesa.com/interop.htm),
70 participating in the development and testing of the
71 [W3C XML Schema Patterns for Databinding Interoperability](http://www.w3.org/2002/ws/databinding),
72 and continues by contributing to the development of
73 [OASIS open standards](https://www.oasis-open.org) in partnership with leading
74 IT companies.
75 
76 🔝 [Back to table of contents](#)
77 
78 Mapping WSDL and XML schemas to C/C++ {#tocpp}
79 =====================================
80 
81 To convert WSDL and XML schemas (XSD files) to code, use the wsdl2h command to
82 generate the data binding interface code that is saved to a special gSOAP
83 header file with WSDL service declarations and the data binding interface:
84 
85  wsdl2h [options] -o file.h ... XSD and WSDL files ...
86 
87 This command converts WSDL and XSD files to C++ (or pure C with wsdl2h option
88 `-c`) and saves the data binding interface to a gSOAP header file `file.h` that
89 uses familiar C/C++ syntax extended with `//gsoap` [directives](#directives)
90 and annotations. Notational conventions are used in the data binding interface
91 to declare serializable C/C++ types and functions for Web service operations.
92 
93 The WSDL 1.1/2.0, SOAP 1.1/1.2, and XSD 1.0/1.1 standards are supported by the
94 gSOAP tools. In addition, the most popular WS specifications are also
95 supported, including WS-Addressing, WS-ReliableMessaging, WS-Discovery,
96 WS-Security, WS-Policy, WS-SecurityPolicy, and WS-SecureConversation.
97 
98 This document focusses on XML data bindings. XML data bindings for C/C++ bind
99 XML schema types to C/C++ types. So integers in XML are bound to C integers,
100 strings in XML are bound to C or C++ strings, complex types in XML are bound to
101 C structs or C++ classes, and so on.
102 
103 A data binding is dual. Either you start with WSDLs and/or XML schemas that
104 are mapped to equivalent C/C++ types, or you start with C/C++ types that are
105 mapped to XSD types. Either way, the end result is that you can serialize
106 C/C++ types in XML such that your XML is an instance of XML schema(s) and is
107 validated against these schema(s).
108 
109 This covers all of the following standard XSD components with their optional
110 attributes and properties:
111 
112 XSD component | attributes and properties
113 -------------- | -------------------------
114 schema | targetNamespace, version, elementFormDefault, attributeFormDefault, defaultAttributes
115 attribute | name, ref, type, use, default, fixed, form, targetNamespace, wsdl:arrayType
116 element | name, ref, type, default, fixed, form, nillable, abstract, substitutionGroup, minOccurs, maxOccurs, targetNamespace
117 simpleType | name
118 complexType | name, abstract, mixed, defaultAttributesApply
119 all | *n/a*
120 choice | minOccurs, maxOccurs
121 sequence | minOccurs, maxOccurs
122 group | name, ref, minOccurs, maxOccurs
123 attributeGroup | name, ref
124 any | minOccurs, maxOccurs
125 anyAttribute | *n/a*
126 
127 And also the following standard XSD directives are covered:
128 
129 directive | description
130 ---------- | -----------
131 import | Imports a schema into the importing schema for referencing
132 include | Include schema component definitions into a schema
133 override | Override by replacing schema component definitions
134 redefine | Extend or restrict schema component definitions
135 annotation | Annotates a component
136 
137 The XSD facets and their mappings to C/C++ are:
138 
139 XSD facet | maps to
140 -------------- | -------
141 enumeration | `enum`
142 simpleContent | class/struct wrapper with `__item` member
143 complexContent | class/struct
144 list | `enum*` bitmask (`enum*` enumerates up to 64 bit masks)
145 extension | class/struct inheritance/extension
146 restriction | `typedef` and class/struct inheritance/redeclaration
147 length | `typedef` with restricted content length annotation
148 minLength | `typedef` with restricted content length annotation
149 maxLength | `typedef` with restricted content length annotation
150 minInclusive | `typedef` with numerical value range restriction annotation
151 maxInclusive | `typedef` with numerical value range restriction annotation
152 minExclusive | `typedef` with numerical value range restriction annotation
153 maxExclusive | `typedef` with numerical value range restriction annotation
154 precision | `typedef` with pattern annotation (pattern used for output, but input is not validated)
155 scale | `typedef` with pattern annotation (pattern used for output, but input is not validated)
156 totalDigits | `typedef` with pattern annotation (pattern used for output, but input is not validated)
157 fractionDigits | `typedef` with pattern annotation (pattern used for output, but input is not validated)
158 pattern | `typedef` with pattern annotation (define `soap::fsvalidate` callback to validate patterns)
159 union | string with union of value
160 
161 All primitive XSD types are supported, including but not limited to the
162 following XSD types:
163 
164 XSD type | maps to
165 ---------------- | -------
166 any/anyType | `_XML` string with literal XML content (or enable DOM with wsdl2h option `-d`)
167 anyURI | string (i.e. `char*`, `wchar_t*`, `std::string`, `std::wstring`)
168 string | string (i.e. `char*`, `wchar_t*`, `std::string`, `std::wstring`)
169 boolean | `bool` (C++) or `enum xsd__boolean` (C)
170 byte | `char` (i.e. `int8_t`)
171 short | `short` (i.e. `int16_t`)
172 int | `int` (i.e. `int32_t`)
173 long | `LONG64` (i.e. `long long` and `int64_t`)
174 unsignedByte | `unsigned char` (i.e. `uint8_t`)
175 unsignedShort | `unsigned short` (i.e. `uint16_t`)
176 unsignedInt | `unsigned int` (i.e. `uint32_t`)
177 unsignedLong | `ULONG64` (i.e. `unsigned long long` and `uint64_t`)
178 float | `float`
179 double | `double`
180 integer | string or `#import "custom/int128.h"` to use 128 bit `xsd__integer`
181 decimal | string or `#import "custom/long_double.h"` to use `long double`
182 precisionDecimal | string
183 duration | string or `#import "custom/duration.h"` to use 64 bit `xsd__duration`
184 dateTime | `time_t` or `#import "custom/struct_tm.h"` to use `struct tm` for `xsd__dateTime`
185 time | string or `#import "custom/long_time.h"` to use 64 bit `xsd__time`
186 date | string or `#import "custom/struct_tm_date.h"` to use `struct tm` for `xsd__date`
187 hexBinary | special class/struct `xsd__hexBinary`
188 base64Bianry | special class/struct `xsd__base64Binary`
189 QName | `_QName` string (URI normalization rules are applied)
190 
191 All other primitive XSD types not listed above are mapped to strings, by
192 wsdl2h generating a typedef to string for these types. For example,
193 `xsd:token` is bound to a C++ or C string:
194 
195 ```cpp
196 typedef std::string xsd__token; // C++
197 typedef char *xsd__token; // C (wsdl2h option -c)
198 ```
199 
200 This associates a compatible value space to the type with the appropriate XSD
201 type name used by the soapcpp2-generated serializers.
202 
203 It is possible to remap types by adding the appropriate mapping rules to
204 `typemap.dat` as we will explain in more detail in the next section.
205 
206 Imported custom serializers are intended to extend the C/C++ type bindings when
207 the default binding to string is not satisfactory to your taste and if the
208 target platform supports these C/C++ types. To add custom serializers to
209 `typemap.dat` for wsdl2h, see [adding custom serializers](#custom) below.
210 
211 🔝 [Back to table of contents](#)
212 
213 Using typemap.dat to customize data bindings {#typemap}
214 ============================================
215 
216 Use a `typemap.dat` file to redefine namespace prefixes and to customize type
217 bindings for the the generated header files produced by the wsdl2h tool. The
218 `typemap.dat` is the default file processed by wsdl2h. Use wsdl2h option `-t`
219 to specify a different file.
220 
221 Declarations in `typemap.dat` can be broken up over multiple lines by
222 continuing on the next line by ending each line to be continued with a
223 backslash `\`. The limit is 4095 characters per line, whether the line is
224 broken up or not.
225 
226 🔝 [Back to table of contents](#)
227 
228 XML namespace bindings {#typemap1}
229 ----------------------
230 
231 The wsdl2h tool generates C/C++ type declarations that use `ns1`, `ns2`, etc.
232 as schema-binding URI prefixes. These default prefixes are generated somewhat
233 arbitrarily for each schema targetNamespace URI, meaning that their ordering
234 may change depending on the WSDL and XSD order of processing with wsdl2h.
235 
236 Therefore, it is **strongly recommended** to declare your own prefix for each
237 schema URI in `typemap.dat` to reduce maintaince effort of your code. This
238 is more robust when anticipating possible changes of the schema(s) and/or the
239 binding URI(s) and/or the tooling algorithms.
240 
241 The first and foremost important thing to do is to define prefix-URI bindings
242 for our C/C++ code by adding the following line(s) to our `typemap.dat` or make
243 a copy of this file and add the line(s) that bind our choice of prefix name to
244 each URI:
245 
246  prefix = "URI"
247 
248 For example, to use `g` as a prefix for the "urn:graph" XML namespace:
249 
250  g = "urn:graph"
251 
252 This produces `g__name` C/C++ type names that are bound to the "urn:graph"
253 schema by association of `g` to the generated C/C++ types.
254 
255 This means that `<g:name xmlns:g="urn:graph">` is parsed as an instance of a
256 `g__name` C/C++ type. Also `<x:name xmlns:x="urn:graph">` parses as an
257 instance of `g__name`, because the prefix `x` has the same URI value
258 `urn:graph`. Prefixes in XML have local scopes (like variables in a block).
259 
260 The first run of wsdl2h will reveal the XML namespace URIs, so you do not need
261 to search WSDLs and XSD files for all of the target namespaces. Just copy them
262 from the generated header file after the first run into `typemap.dat` for
263 editing.
264 
265 @note Only define a namespace prefix once in `typemap.dat`. That is, do not
266 use the same prefix for multiple XML namespace URIs. This is to avoid
267 namespace conflicts that may cause failed builds and failures in XML parsing
268 and XML schema validation.
269 
270 🔝 [Back to table of contents](#)
271 
272 XSD type bindings {#typemap2}
273 -----------------
274 
275 Custom C/C++ type bindings can be declared in `typemap.dat` to associate C/C++
276 types with specific schema types. These type bindings have four parts:
277 
278  prefix__type = declaration | use | ptruse
279 
280 where
281 
282 - `prefix__type` is the schema type to be customized (the `prefix__type` name
283  uses the common double underscore naming convention);
284 - `declaration` declares the C/C++ type in the wsdl2h-generated header file.
285  This part can be empty if no explicit declaration is needed;
286 - `use` is an optional part that specifies how the C/C++ type is used in the
287  code. When omitted, it is the same as `prefix__type`;
288 - `ptruse` is an optional part that specifies how the type is used as a pointer
289  type. By default it is the `use` type name with a `*` or C++11
290  `std::shared_ptr<>` when enabled (see further below). If `use` is already a
291  pointer type by the presence of a `*` in the `use` part, then the default
292  `ptruse` type is the same as the `use` type (that is, no double pointer `**`
293  will be created in this case).
294 
295 For example, to map `xsd:duration` to a `long long` (`LONG64`) type that holds
296 millisecond duration values, we can use the custom serializer declared in
297 `custom/duration.h` by adding the following line to `typemap.dat`:
298 
299  xsd__duration = #import "custom/duration.h"
300 
301 Here, we omitted the second and third parts, because `xsd__duration` is the
302 name that wsdl2h uses for this type in our generated code so we should leave
303 the `use` part unspecified. The third part is omitted to let wsdl2h use
304 `xsd__duration *` for pointers or `std::shared_ptr<xsd__duration>` if smart
305 pointers are enabled.
306 
307 To map `xsd:string` to `wchar_t*` wide strings:
308 
309  xsd__string = | wchar_t* | wchar_t*
310 
311 Note that the first part is empty, because `wchar_t` is a C type and does not
312 need to be declared. A `ptruse` part is also defined in this example, but does
313 not need to be because the `use` part `wchar_t*` is already a pointer.
314 
315 When the auto-generated declaration should be preserved but the `use` or
316 `ptruse` parts replaced, then we use an ellipsis for the declaration part:
317 
318  prefix__type = ... | use | ptruse
319 
320 This is useful to map schema polymorphic types to C types for example, where we
321 need to be able to both handle a base type and its extensions as per schema
322 extensibility. Say we have a base type called ns:base that is extended, then we
323 can remap this to a C type that permits referening the extended types via a
324 `void*` as follows:
325 
326  ns__base = ... | int __type_base; void*
327 
328 such that `__type_base` and `void*` will be used to (de)serialize any data
329 type, including base and its derived types. The `__type_base` integer is set
330 to a `SOAP_TYPE_T` value to indicate what type of data the `void*` pointer
331 points to.
332 
333 🔝 [Back to table of contents](#)
334 
335 Custom serializers for XSD types {#custom}
336 --------------------------------
337 
338 In the previous part we saw how a custom serializer is used to bind
339 `xsd:duration` to a `long long` (`LONG64` or `int64_t`) type to store millisecond
340 duration values:
341 
342  xsd__duration = #import "custom/duration.h"
343 
344 The `xsd__duration` type is an alias of `long long` (`LONG64` or `int64_t`).
345 
346 While wsdl2h will use this binding declared in `typemap.dat` automatically, you
347 will also need to compile `custom/duration.c`. Each custom serializer has a
348 header file and an implementation file written in C. You can compile these in
349 C++ (rename files to `.cpp` if needed).
350 
351 We will discuss the custom serializers that are available to you.
352 
353 🔝 [Back to table of contents](#)
354 
355 ### xsd:integer {#custom-1}
356 
357 The wsdl2h tool maps `xsd:integer` to a string by default. To map `xsd:integer` to
358 the 128 bit big int type `__int128_t`:
359 
360  xsd__integer = #import "custom/int128.h"
361 
362 The `xsd__integer` type is an alias of `__int128_t`.
363 
364 @warning Beware that the `xsd:integer` value space of integers is in principle
365 unbounded and values can be of arbitrary length. A value range fault
366 `SOAP_TYPE` (value exceeds native representation) or `SOAP_LENGTH` (value
367 exceeds range bounds) will be thrown by the deserializer if the value is out of
368 range.
369 
370 Other XSD integer types that are restrictions of `xsd:integer`, are
371 `xsd:nonNegativeInteger` and `xsd:nonPositiveInteger`, which are further restricted
372 by `xsd:positiveInteger` and `xsd:negativeInteger`. To bind these types to
373 `__int128_t` add the following definitions to `typemap.dat`:
374 
375  xsd__nonNegativeInteger = typedef xsd__integer xsd__nonNegativeInteger 0 : ;
376  xsd__nonPositiveInteger = typedef xsd__integer xsd__nonPositiveInteger : 0 ;
377  xsd__positiveInteger = typedef xsd__integer xsd__positiveInteger 1 : ;
378  xsd__negativeInteger = typedef xsd__integer xsd__negativeInteger : -1 ;
379 
380 Or simply uncomment these definitions in `typemap.dat` when you are using the
381 latest gSOAP releases.
382 
383 @note If `__int128_t` 128 bit integers are not supported on your platform and if it
384 is certain that `xsd:integer` values are within 64 bit value bounds for your
385 application's use, then you can map this type to `LONG64`:
386 
387  xsd__integer = typedef LONG64 xsd__integer;
388 
389 @note Again, a value range fault `SOAP_TYPE` or `SOAP_LENGTH` will be thrown by
390 the deserializer if the value is out of range.
391 
392 After running wsdl2h and soapcpp2, compile `custom/int128.c` with your project.
393 
394 @see Section [numerical types](#toxsd5).
395 
396 🔝 [Back to table of contents](#)
397 
398 ### xsd:decimal {#custom-2}
399 
400 The wsdl2h tool maps `xsd:decimal` to a string by default. To map `xsd:decimal` to
401 extended precision floating point:
402 
403  xsd__decimal = #import "custom/long_double.h" | long double
404 
405 By contrast to all other custom serializers, this serializer enables `long
406 double` natively without requiring a new binding name (`xsd__decimal` is NOT
407 defined).
408 
409 If your system supports `<quadmath.h>` quadruple precision floating point
410 `__float128`, you can map `xsd:decimal` to `xsd__decimal` that is an alias of
411 `__float128`:
412 
413  xsd__decimal = #import "custom/float128.h"
414 
415 @warning Beware that `xsd:decimal` is in principle a decimal value with arbitraty
416 lengths. A value range fault `SOAP_TYPE` will be thrown by the deserializer if
417 the value is out of range.
418 
419 In the XML payload the special values `INF`, `-INF`, `NaN` represent plus or
420 minus infinity and not-a-number, respectively.
421 
422 After running wsdl2h and soapcpp2, compile `custom/long_double.c` with your
423 project.
424 
425 @see Section [numerical types](#toxsd5).
426 
427 🔝 [Back to table of contents](#)
428 
429 ### xsd:dateTime {#custom-3}
430 
431 The wsdl2h tool maps `xsd:dateTime` to `time_t` by default.
432 
433 The trouble with `time_t` when represented as 32 bit `long` integers is that it
434 is limited to dates between 1970 and 2038. A 64 bit `time_t` is safe to use if
435 the target platform supports it, but lack of 64 bit `time_t` portability may
436 still cause date range issues.
437 
438 For this reason `struct tm` should be used to represent wider date ranges. This
439 custom serializer avoids using date and time information in `time_t`. You get
440 the raw date and time information. You only lose the day of the week
441 information. It is always Sunday (`tm_wday=0`).
442 
443 To map `xsd:dateTime` to `xsd__dateTime` which is an alias of `struct tm`:
444 
445  xsd__dateTime = #import "custom/struct_tm.h"
446 
447 If the limited date range of `time_t` is not a problem but you want to increase
448 the time precision with fractional seconds, then we suggest to map `xsd:dateTime`
449 to `struct timeval`:
450 
451  xsd__dateTime = #import "custom/struct_timeval.h"
452 
453 If the limited date range of `time_t` is not a problem but you want to use the
454 C++11 time point type `std::chrono::system_clock::time_point` (which internally
455 uses `time_t`):
456 
457  xsd__dateTime = #import "custom/chrono_time_point.h"
458 
459 Again, we should make sure that the dates will not exceed the date range when
460 using the default `time_t` binding for `xsd:dateTime` or when binding
461 `xsd:dateTime` to `struct timeval` or to `std::chrono::system_clock::time_point`.
462 These are safe to use in applications that use `xsd:dateTime` to record date
463 stamps within a given window. Otherwise, we recommend the `struct tm` custom
464 serializer.
465 
466 After running wsdl2h and soapcpp2, compile `custom/struct_tm.c` with your
467 project.
468 
469 You could even map `xsd:dateTime` to a plain string (use `char*` with C and
470 `std::string` with C++). For example:
471 
472  xsd__dateTime = | char*
473 
474 @see Section [date and time types](#toxsd7).
475 
476 🔝 [Back to table of contents](#)
477 
478 ### xsd:date {#custom-4}
479 
480 The wsdl2h tool maps `xsd:date` to a string by default. We can map `xsd:date` to
481 `struct tm`:
482 
483  xsd__date = #import "custom/struct_tm_date.h"
484 
485 The `xsd__date` type is an alias of `struct tm`. The serializer ignores the
486 time part and the deserializer only populates the date part of the struct,
487 setting the time to 00:00:00. There is no unreasonable limit on the date range
488 because the year field is stored as an integer (`int`).
489 
490 After running wsdl2h and soapcpp2, compile `custom/struct_tm_date.c` with your
491 project.
492 
493 @see Section [date and time types](#toxsd7).
494 
495 🔝 [Back to table of contents](#)
496 
497 ### xsd:time {#custom-5}
498 
499 The wsdl2h tool maps `xsd:time` to a string by default. We can map `xsd:time` to
500 an `unsigned long long` (`ULONG64` or `uint64_t`) integer with microsecond time
501 precision:
502 
503  xsd__time = #import "custom/long_time.h"
504 
505 This type represents 00:00:00.000000 to 23:59:59.999999, from `0` to an upper
506 bound of `86399999999`. A microsecond resolution means that a 1 second
507 increment requires an increment of 1000000 in the integer value. The serializer
508 adds a UTC time zone.
509 
510 After running wsdl2h and soapcpp2, compile `custom/long_time.c` with your
511 project.
512 
513 @see Section [date and time types](#toxsd7).
514 
515 🔝 [Back to table of contents](#)
516 
517 ### xsd:duration {#custom-6}
518 
519 The wsdl2h tool maps `xsd:duration` to a string by default, unless `xsd:duration`
520 is mapped to a `long long` (`LONG64` or `int64_t`) type with with millisecond
521 (ms) time duration precision:
522 
523  xsd__duration = #import "custom/duration.h"
524 
525 The `xsd__duration` type is a 64 bit signed integer that can represent
526 106,751,991,167 days forwards (positive) and backwards (negative) in time in
527 increments of 1 ms (1/1000 of a second).
528 
529 Rescaling of the duration value by may be needed when adding the duration value
530 to a `time_t` value, because `time_t` may or may not have a seconds resolution,
531 depending on the platform and possible changes to `time_t`.
532 
533 Rescaling is done automatically when you add a C++11 `std::chrono::nanoseconds`
534 value to a `std::chrono::system_clock::time_point` value. To use
535 `std::chrono::nanoseconds` as `xsd:duration`:
536 
537  xsd__duration = #import "custom/chrono_duration.h"
538 
539 This type can represent 384,307,168 days (2^63 nanoseconds) forwards and
540 backwards in time in increments of 1 ns (1/1,000,000,000 of a second).
541 
542 Certain observations with respect to receiving durations in years and months
543 apply to both of these serializer decoders for `xsd:duration`.
544 
545 After running wsdl2h and soapcpp2, compile `custom/duration.c` with your
546 project.
547 
548 @see Section [time duration types](#toxsd8).
549 
550 🔝 [Back to table of contents](#)
551 
552 Custom Qt serializers for XSD types {#qt}
553 -----------------------------------
554 
555 The gSOAP distribution includes several custom serializers for Qt types. Also
556 Qt container classes are supported, see
557 [the built-in typemap.dat variables $CONTAINER and $POINTER](#typemap5).
558 
559 This feature requires gSOAP 2.8.34 or higher and Qt 4.8 or higher.
560 
561 Each Qt custom serializer has an interface header file for soapcpp2 and a C++
562 implementation file to be compiled with your project.
563 
564 Other Qt primitive types that are Qt typedefs of C/C++ types do not require a
565 custom serializer.
566 
567 🔝 [Back to table of contents](#)
568 
569 ### xsd:string {#qt-1}
570 
571 To use Qt strings instead of C++ strings, add the following definition to
572 `typemap.dat`:
573 
574  xsd__string = #import "custom/qstring.h"
575 
576 After running wsdl2h and soapcpp2, compile `custom/qstring.cpp` with your
577 project.
578 
579 🔝 [Back to table of contents](#)
580 
581 ### xsd:base64Binary {#qt-2}
582 
583 To use Qt byte arrays for `xsd:base64Binary` instead of the
584 `xsd__base64Binary` class, add the following definition to `typemap.dat`:
585 
586  xsd__base64Binary = #import "custom/qbytearray_base64.h"
587 
588 After running wsdl2h and soapcpp2, compile `custom/qbytearray_base64.cpp` with
589 your project.
590 
591 🔝 [Back to table of contents](#)
592 
593 ### xsd:hexBinary {#qt-3}
594 
595 To use Qt byte arrays for `xsd:hexBinary` instead of the `xsd__base64Binary`
596 class, add the following definition to `typemap.dat`:
597 
598  xsd__hexBinary = #import "custom/qbytearray_hex.h"
599 
600 After running wsdl2h and soapcpp2, compile `custom/qbytearray_hex.cpp` with
601 your project.
602 
603 🔝 [Back to table of contents](#)
604 
605 ### xsd:dateTime {#qt-4}
606 
607 To use Qt QDateTime for `xsd:dateTime`, add the following definition to
608 `typemap.dat`:
609 
610  xsd__dateTime = #import "custom/datetime.h"
611 
612 After running wsdl2h and soapcpp2, compile `custom/qdatetime.cpp` with
613 your project.
614 
615 🔝 [Back to table of contents](#)
616 
617 ### xsd:date {#qt-5}
618 
619 To use Qt QDate for `xsd:date`, add the following definition to
620 `typemap.dat`:
621 
622  xsd__date = #import "custom/qdate.h"
623 
624 After running wsdl2h and soapcpp2, compile `custom/qdate.cpp` with your
625 project.
626 
627 🔝 [Back to table of contents](#)
628 
629 ### xsd:time {#qt-6}
630 
631 To use Qt QDate for `xsd:time`, add the following definition to
632 `typemap.dat`:
633 
634  xsd__time = #import "custom/qtime.h"
635 
636 After running wsdl2h and soapcpp2, compile `custom/qtime.cpp` with your
637 project.
638 
639 🔝 [Back to table of contents](#)
640 
641 Class/struct member additions {#typemap3}
642 -----------------------------
643 
644 All generated classes and structs can be augmented with additional
645 members such as methods, constructors and destructors, and private members:
646 
647  prefix__type = $ member-declaration
648 
649 For example, we can add method declarations and private members to a class, say
650 `ns__record` as follows:
651 
652  ns__record = $ ns__record(const ns__record &); // copy constructor
653  ns__record = $ void print(); // a print method
654  ns__record = $ private: int status; // a private member
655 
656 Note that method declarations cannot include any code, because soapcpp2's input
657 permits only type declarations, not code.
658 
659 🔝 [Back to table of contents](#)
660 
661 Replacing XSD types by equivalent alternatives {#typemap4}
662 ----------------------------------------------
663 
664 Type replacements can be given to replace one type entirely with another given
665 type:
666 
667  prefix__type1 == prefix__type2
668 
669 This replaces all `prefix__type1` by `prefix__type2` in the wsdl2h output.
670 
671 @warning Do not agressively replace types, because this can cause XML schema
672 validation to fail when a value-type mismatch is encountered in the XML input.
673 Therefore, only replace similar types with other similar types that are wider
674 (e.g. `short` by `int` and `float` by `double`).
675 
676 🔝 [Back to table of contents](#)
677 
678 The built-in typemap.dat variables $CONTAINER and $POINTER {#typemap5}
679 ----------------------------------------------------------
680 
681 The `typemap.dat` `$CONTAINER` variable defines the container to emit in the
682 generated declarations, which is `std::vector` by default. For example, to emit
683 `std::list` as the container in the wsdl2h-generated declarations:
684 
685  $CONTAINER = std::list
686 
687 The `typemap.dat` `$POINTER` variable defines the smart pointer to emit in the
688 generated declarations, which replaces the use of `*` pointers. For example:
689 
690  $POINTER = std::shared_ptr
691 
692 Not all pointers in the generated output can be replaced by smart pointers.
693 Regular pointers are still used as union members and for pointers to arrays of
694 objects.
695 
696 @note The standard smart pointer `std::shared_ptr` is generally safe to use.
697 Other smart pointers such as `std::unique_ptr` and `std::auto_ptr` may cause
698 compile-time errors when classes have smart pointer members but no copy
699 constructor (a default copy constructor). A copy constructor is required for
700 non-shared smart pointer copying or swapping.
701 
702 Alternatives to `std::shared_ptr` of the form `NAMESPACE::shared_ptr` can be
703 assigned to `$POINTER` when the namespace `NAMESPACE` also implements
704 `NAMESPACE::make_shared` and when the shared pointer class provides `reset()`
705 and`get()` methods and the dereference operator. For example Boost
706 `boost::shared_ptr`:
707 
708  [
709  #include <boost/shared_ptr.hpp>
710  ]
711  $POINTER = boost::shared_ptr
712 
713 The user-defined content between `[` and `]` ensures that we include the Boost
714 header files that are needed to support `boost::shared_ptr` and
715 `boost::make_shared`.
716 
717 A Qt container can be used instead of the default `std::vector`, for example
718 `QVector`:
719 
720  [
721  #include <QVector>
722  ]
723  $CONTAINER = QVector
724 
725 🔝 [Back to table of contents](#)
726 
727 User-defined content {#typemap6}
728 --------------------
729 
730 Any other content to be generated by wsdl2h can be included in `typemap.dat` by
731 enclosing it within brackets `[` and `]` anywhere in the `typemap.dat` file.
732 Each of the two brackets MUST appear at the start of a new line.
733 
734 For example, we can add an `#import "wsa5.h"` to the wsdl2h-generated output as
735 follows:
736 
737  [
738  #import "import/wsa5.h"
739  ]
740 
741 which emits the `#import "import/wsa5.h"` literally at the start of the
742 wsdl2h-generated header file.
743 
744 🔝 [Back to table of contents](#)
745 
746 Mapping C/C++ to XML schema {#toxsd}
747 ===========================
748 
749 The soapcpp2 command generates the data binding implementation code from a data
750 binding interface `file.h`:
751 
752  soapcpp2 [options] file.h
753 
754 where `file.h` is a gSOAP header file that declares the XML data binding
755 interface. The `file.h` is typically generated by wsdl2h, but you can also
756 declare one yourself. If so, add `//gsaop` [directives](#directives) and
757 declare in this file all our C/C++ types you want to serialize in XML.
758 
759 You can also declare functions that will be converted to Web service operations
760 by soapcpp2. Global function declarations define service operations, which are
761 of the form:
762 
763 ```cpp
764 int prefix__func(arg1, arg2, ..., argn, result);
765 ```
766 
767 where `arg1`, `arg2`, ..., `argn` are formal argument declarations of the input
768 and `result` is a formal argument for the output, which must be a pointer or
769 reference to the result object to be populated. More information can be found
770 in the [gSOAP user guide.](http://www.genivia.com/doc/soapdoc2.html)
771 
772 🔝 [Back to table of contents](#)
773 
774 Overview of serializable C/C++ types {#toxsd1}
775 ------------------------------------
776 
777 The following C/C++ types are supported by soapcpp2 and mapped to XSD types
778 and constructs. See the subsections below for more details or follow the links.
779 
780 🔝 [Back to table of contents](#)
781 
782 ### List of Boolean types
783 
784 | Boolean Type | Notes |
785 | ----------------------------- | ----------------------------------------------------------------------------------- |
786 | `bool` | C++ bool |
787 | `enum xsd__boolean` | C alternative to C++ `bool` with `false_` and `true_` |
788 
789 @see Section [C++ bool and C alternative](#toxsd3).
790 
791 🔝 [Back to table of contents](#)
792 
793 ### List of enumeration and bitmask types
794 
795 | Enumeration Type | Notes |
796 | ----------------------------- | ----------------------------------------------------------------------------------- |
797 | `enum` | enumeration |
798 | `enum class` | C++11 scoped enumeration (soapcpp2 `-c++11`) |
799 | `enum*` | a bitmask that enumerates values 1, 2, 4, 8, ... |
800 | `enum* class` | C++11 scoped enumeration bitmask (soapcpp2 `-c++11`) |
801 
802 @see Section [enumerations and bitmasks](#toxsd4).
803 
804 🔝 [Back to table of contents](#)
805 
806 ### List of numerical types
807 
808 | Numerical Type | Notes |
809 | ----------------------------- | ----------------------------------------------------------------------------------- |
810 | `char` | byte |
811 | `short` | 16 bit integer |
812 | `int` | 32 bit integer |
813 | `long` | 32 bit integer |
814 | `LONG64` | 64 bit integer |
815 | `xsd__integer` | 128 bit integer, use `#import "custom/int128.h"` |
816 | `long long` | same as `LONG64` |
817 | `unsigned char` | unsigned byte |
818 | `unsigned short` | unsigned 16 bit integer |
819 | `unsigned int` | unsigned 32 bit integer |
820 | `unsigned long` | unsigned 32 bit integer |
821 | `ULONG64` | unsigned 64 bit integer |
822 | `unsigned long long` | same as `ULONG64` |
823 | `int8_t` | same as `char` |
824 | `int16_t` | same as `short` |
825 | `int32_t` | same as `int` |
826 | `int64_t` | same as `LONG64` |
827 | `uint8_t` | same as `unsigned char` |
828 | `uint16_t` | same as `unsigned short` |
829 | `uint32_t` | same as `unsigned int` |
830 | `uint64_t` | same as `ULONG64` |
831 | `size_t` | transient type (not serializable) |
832 | `float` | 32 bit float |
833 | `double` | 64 bit float |
834 | `long double` | extended precision float, use `#import "custom/long_double.h"` |
835 | `xsd__decimal` | `<quadmath.h>` 128 bit quadruple precision float, use `#import "custom/float128.h"` |
836 | `typedef` | declares a type name, with optional value range and string length bounds |
837 
838 @see Section [numerical types](#toxsd5).
839 
840 🔝 [Back to table of contents](#)
841 
842 ### List of string types
843 
844 | String Type | Notes |
845 | ----------------------------- | ----------------------------------------------------------------------------------- |
846 | `char*` | string (may contain UTF-8 with flag `SOAP_C_UTFSTRING`) |
847 | `wchar_t*` | wide string |
848 | `std::string` | C++ string (may contain UTF-8 with flag `SOAP_C_UTFSTRING`) |
849 | `std::wstring` | C++ wide string |
850 | `char[N]` | fixed-size string, requires soapcpp2 option `-b` |
851 | `_QName` | normalized QName content |
852 | `_XML` | literal XML string content with wide characters in UTF-8 |
853 | `typedef` | declares a new string type name, may restrict string length |
854 
855 @see Section [string types](#toxsd6).
856 
857 🔝 [Back to table of contents](#)
858 
859 ### List of date and time types
860 
861 | Date and Time Type | Notes |
862 | --------------------------------------- | ------------------------------------------------------------------------- |
863 | `time_t` | date and time point since epoch |
864 | `struct tm` | date and time point, use `#import "custom/struct_tm.h"` |
865 | `struct tm` | date point, use `#import "custom/struct_tm_date.h"` |
866 | `struct timeval` | date and time point, use `#import "custom/struct_timeval.h"` |
867 | `unsigned long long` | time point in microseconds, use `#import "custom/long_time.h"` |
868 | `std::chrono::system_clock::time_point` | date and time point, use `#import "custom/chrono_time_point.h"` |
869 
870 @see Section [date and time types](#toxsd7).
871 
872 🔝 [Back to table of contents](#)
873 
874 ### List of time duration types
875 
876 | Time Duration Type | Notes |
877 | ----------------------------- | ----------------------------------------------------------------------------------- |
878 | `long long` | duration in milliseconds, use `#import "custom/duration.h"` |
879 | `std::chrono::nanoseconds` | duration in nanoseconds, use `#import "custom/chrono_duration.h"` |
880 
881 @see Section [time duration types](#toxsd8).
882 
883 🔝 [Back to table of contents](#)
884 
885 ### List of classes and structs
886 
887 | Classes, Structs, and Members | Notes |
888 | ----------------------------- | ----------------------------------------------------------------------------------- |
889 | `class` | C++ class with single inheritance only |
890 | `struct` | C struct or C++ struct without inheritance |
891 | `std::shared_ptr<T>` | C++11 smart shared pointer |
892 | `std::unique_ptr<T>` | C++11 smart pointer |
893 | `std::auto_ptr<T>` | C++ smart pointer |
894 | `std::deque<T>` | use `#import "import/stldeque.h"` |
895 | `std::list<T>` | use `#import "import/stllist.h"` |
896 | `std::vector<T>` | use `#import "import/stlvector.h"` |
897 | `std::set<T>` | use `#import "import/stlset.h"` |
898 | `template<T> class` | a container with `begin()`, `end()`, `size()`, `clear()`, and `insert()` methods |
899 | `T*` | data member: pointer to data of type `T` or points to array of `T` of size `__size` |
900 | `T[N]` | data member: fixed-size array of type `T` |
901 | `union` | data member: requires a variant selector member `__union` |
902 | `void*` | data member: requires a `__type` member to indicate the type of object pointed to |
903 
904 @see Section [classes and structs](#toxsd9).
905 
906 🔝 [Back to table of contents](#)
907 
908 ### List of special classes and structs
909 
910 | Special Classes and Structs | Notes |
911 | ----------------------------- | ----------------------------------------------------------------------------------- |
912 | Special Array class/struct | single and multidimensional SOAP Arrays |
913 | Special Wrapper class/struct | complexTypes with simpleContent, wraps `__item` member |
914 | `xsd__hexBinary` | binary content |
915 | `xsd__base64Binary` | binary content and optional MIME/MTOM attachments |
916 | `xsd__anyType` | DOM elements, use `#import "dom.h"` |
917 | `@xsd__anyAttribute` | DOM attributes, use `#import "dom.h"` |
918 
919 @see Section [special classes and structs](#toxsd10).
920 
921 🔝 [Back to table of contents](#)
922 
923 Colon notation versus name prefixing with XML tag name translation {#toxsd2}
924 ------------------------------------------------------------------
925 
926 To bind C/C++ type names to XSD types, a simple form of name prefixing is used
927 by the gSOAP tools by prepending the XML namespace prefix to the C/C++ type
928 name with a pair of undescrores. This also ensures that name clashes cannot
929 occur when multiple WSDL and XSD files are converted to C/C++. Also, C++
930 namespaces are not sufficiently rich to capture XML schema namespaces
931 accurately, for example when class members are associated with schema elements
932 defined in another XML namespace and thus the XML namespace scope of the
933 member's name is relevant, not just its type.
934 
935 However, from a C/C++ centric point of view this can be cumbersome. Therefore,
936 colon notation is an alternative to physically augmenting C/C++ names with
937 prefixes.
938 
939 For example, the following class uses colon notation to bind the `record` class
940 to the `urn:types` schema:
941 
942 ```cpp
943 //gsoap ns schema namespace: urn:types
944 class ns:record // binding 'ns:' to a type name
945 {
946  public:
947  std::string name;
948  uint64_t SSN;
949  ns:record *spouse; // using 'ns:' with the type name
950  ns:record(); // using 'ns:' here too
951  ~ns:record(); // and here
952 };
953 ```
954 
955 The colon notation is stripped away by soapcpp2 when generating the data
956 binding implementation code for our project. So the final code just uses
957 `record` to identify this class and its constructor/destructor.
958 
959 When using colon notation make sure to be consistent and not use colon notation
960 mixed with prefixed forms. The name `ns:record` differs from `ns__record`,
961 because `ns:record` is compiled to an unqualified `record` name.
962 
963 Colon notation also facilitates overruling the elementFormDefault and
964 attributeFormDefault declaration that is applied to local elements and
965 attributes, when declared as members of classes, structs, and unions. For more
966 details, see [qualified and unqualified members](#toxsd9-6).
967 
968 A C/C++ identifier name (a type name, member name, function name, or parameter
969 name) is translated to an XML tag name by the following rules:
970 
971 - Two leading underscores indicates that the identifier name has no XML tag
972  name, i.e. this name is not visible in XML and is not translated.
973 - A leading underscore is removed, but the underscore indicates that: **a**) a
974  struct/class member name or parameter name has a wildcard XML tag name (i.e.
975  matches any XML tag), or **b**) a type name that has a
976  [document root element definition](#toxsd9-7).
977 - Trailing underscores are removed (i.e. trailing underscores can be used to
978  avoid name clashes with keywords).
979 - Underscores within names are translated to hyphens (hyphens are more common
980  in XML tags).
981 - `_USCORE` is translated to an underscore in the translated XML tag name.
982 - `_DOT` is translated to a dot (`.`) in the translated XML tag name.
983 - `_xHHHH` is translated to the Unicode character with code point HHHH (hex).
984 - C++11 Unicode identifier name characters in UTF-8 are translated as-is.
985 
986 For example, the C/C++ namespace qualified identifier name `s_a__my_way` is
987 translated to the XML tag name `s-a:my-way` by translating the prefix `s_a`
988 and the local name `my_way`.
989 
990 Struct/class member and parameter name translation can be overruled by using
991 [backtick XML tags](#toxsd9-5) (with gSOAP 2.8.30 and later versions).
992 
993 🔝 [Back to table of contents](#)
994 
995 C++ Bool and C alternatives {#toxsd3}
996 ---------------------------
997 
998 The C++ `bool` type is bound to built-in XSD type `xsd:boolean`.
999 
1000 The C alternative is to define an enumeration:
1001 
1002 ```cpp
1003 enum xsd__boolean { false_, true_ };
1004 ```
1005 
1006 or by defining an enumeration in C with pseudo-scoped enumeration constants:
1007 
1008 ```cpp
1009 enum xsd__boolean { xsd__boolean__false, xsd__boolean__true };
1010 ```
1011 
1012 The XML value space of these types is `false` and `true`, but also accepted
1013 are `0` and `1` values for false and true, respectively.
1014 
1015 To prevent name clashes, `false_` and `true_` have an underscore. Trailing
1016 underscores are removed from the XML value space.
1017 
1018 🔝 [Back to table of contents](#)
1019 
1020 Enumerations and bitmasks {#toxsd4}
1021 -------------------------
1022 
1023 Enumerations are mapped to XSD simpleType enumeration restrictions of
1024 `xsd:string`, `xsd:QName`, and `xsd:long`.
1025 
1026 Consider for example:
1027 
1028 ```cpp
1029 enum ns__Color { RED, WHITE, BLUE };
1030 ```
1031 
1032 which maps to a simpleType restriction of `xsd:string` in the soapcpp2-generated
1033 schema:
1034 
1035 <div class="alt">
1036 ```xml
1037 <simpleType name="Color">
1038  <restriction base="xsd:string">
1039  <enumeration value="RED"/>
1040  <enumeration value="WHITE"/>
1041  <enumeration value="BLUE"/>
1042  </restriction>
1043 </simpleType>
1044 ```
1045 </div>
1046 
1047 Enumeration name constants can be pseudo-scoped to prevent name clashes,
1048 because enumeration name constants have a global scope in C and C++:
1049 
1050 ```cpp
1051 enum ns__Color { ns__Color__RED, ns__Color__WHITE, ns__Color__BLUE };
1052 ```
1053 
1054 You can also use C++11 scoped enumerations to prevent name clashes:
1055 
1056 ```cpp
1057 enum class ns__Color : int { RED, WHITE, BLUE };
1058 ```
1059 
1060 Here, the enumeration class base type `: int` is optional. In place of `int`
1061 in the example above, we can also use `int8_t`, `int16_t`, `int32_t`, or
1062 `int64_t`.
1063 
1064 The XML value space of the enumertions defined above is `RED`, `WHITE`, and
1065 `BLUE`.
1066 
1067 Prefix-qualified enumeration name constants are mapped to simpleType
1068 restrictions of `xsd:QName`, for example:
1069 
1070 ```cpp
1071 enum ns__types { xsd__int, xsd__float };
1072 ```
1073 
1074 which maps to a simpleType restriction of `xsd:QName` in the soapcpp2-generated
1075 schema:
1076 
1077 <div class="alt">
1078 ```xml
1079 <simpleType name="types">
1080  <restriction base="xsd:QName">
1081  <enumeration value="xsd:int"/>
1082  <enumeration value="xsd:float"/>
1083  </restriction>
1084 </simpleType>
1085 ```
1086 </div>
1087 
1088 Enumeration name constants can be pseudo-numeric as follows:
1089 
1090 ```cpp
1091 enum ns__Primes { _3 = 3, _5 = 5, _7 = 7, _11 = 11 };
1092 ```
1093 
1094 which maps to a simpleType restriction of `xsd:long`:
1095 
1096 <div class="alt">
1097 ```xml
1098 <simpleType name="Color">
1099  <restriction base="xsd:long">
1100  <enumeration value="3"/>
1101  <enumeration value="5"/>
1102  <enumeration value="7"/>
1103  <enumeration value="11"/>
1104  </restriction>
1105 </simpleType>
1106 ```
1107 </div>
1108 
1109 The XML value space of this type is `3`, `5`, `7`, and `11`.
1110 
1111 Besides (pseudo-) scoped enumerations, another way to prevent name clashes
1112 accross enumerations is to start an enumeration name constant with one
1113 underscore or followed it by any number of underscores, which makes it
1114 unique. The leading and trailing underscores are removed from the XML value
1115 space.
1116 
1117 ```cpp
1118 enum ns__ABC { A, B, C };
1119 enum ns__BA { B, A }; // BAD: B = 1 but B is already defined as 2
1120 enum ns__BA_ { B_, A_ }; // OK
1121 ```
1122 
1123 The gSOAP soapcpp2 tool permits reusing enumeration name constants across
1124 (non-scoped) enumerations as long as these values are assigned the same
1125 constant. Therefore, the following is permitted:
1126 
1127 ```cpp
1128 enum ns__Primes { _3 = 3, _5 = 5, _7 = 7, _11 = 11 };
1129 enum ns__Throws { _1 = 1, _2 = 2, _3 = 3, _4 = 4, _5 = 5, _6 = 6 };
1130 ```
1131 
1132 A bitmask type is an `enum*` "product" enumeration with a geometric,
1133 power-of-two sequence of values assigned to the enumeration constants:
1134 
1135 ```cpp
1136 enum* ns__Options { SSL3, TLS10, TLS11, TLS12 };
1137 ```
1138 
1139 where the product enum assigns 1 to `SSL3`, 2 to `TLS10`, 4 to `TLS11`, and 8
1140 to `TLS12`, which allows these enumeration constants to be used in composing
1141 bitmasks with `|` (bitwise or) `&` (bitwise and), and `~` (bitwise not):
1142 
1143 ```cpp
1144 enum ns__Options options = (enum ns__Options)(SSL3 | TLS10 | TLS11 | TLS12);
1145 if (options & SSL3) // if SSL3 is an option, warn and remove from options
1146 {
1147  warning();
1148  options &= ~SSL3;
1149 }
1150 ```
1151 
1152 The bitmask type maps to a simpleType list restriction of `xsd:string` in the
1153 soapcpp2-generated schema:
1154 
1155 <div class="alt">
1156 ```xml
1157 <simpleType name="Options">
1158  <list>
1159  <restriction base="xsd:string">
1160  <enumeration value="SSL3"/>
1161  <enumeration value="TLS10"/>
1162  <enumeration value="TLS11"/>
1163  <enumeration value="TLS12"/>
1164  </restriction>
1165  </list>
1166 </simpleType>
1167 ```
1168 </div>
1169 
1170 The XML value space of this type consists of all 16 possible subsets of the
1171 four values, represented by an XML string with space-separated values. For
1172 example, the bitmask `TLS10 | TLS11 | TLS12` equals 14 and is represented by
1173 the XML string `TLS10 TLS11 TLS12`.
1174 
1175 You can also use C++11 scoped enumerations with bitmasks:
1176 
1177 ```cpp
1178 enum* class ns__Options { SSL3, TLS10, TLS11, TLS12 };
1179 ```
1180 
1181 The base type of a scoped enumeration bitmask, when explicitly given, is
1182 ignored. The base type is either `int` or `int64_t`, depending on the number
1183 of constants enumerated in the bitmask.
1184 
1185 To convert `enum` name constants and bitmasks to a string, we use the
1186 auto-generated function for enum `T`:
1187 
1188 ```cpp
1189 const char *soap_T2s(struct soap*, enum T val)
1190 ```
1191 
1192 The string returned is stored in an internal buffer of the current `soap`
1193 context, so you MUST copy it to keep it from being overwritten. For example,
1194 use `char *soap_strdup(struct soap*, const char*)`.
1195 
1196 To convert a string to an `enum` constant or bitmask, we use the auto-generated
1197 function
1198 
1199 ```cpp
1200 int soap_s2T(struct soap*, const char *str, enum T *val)
1201 ```
1202 
1203 This function takes the name (or names, space-separated for bitmasks) of
1204 the enumeration constant in a string `str`. Names should be given without the
1205 pseudo-scope prefix and without trailing underscores. The function sets `val`
1206 to the corresponding integer enum constant or to a bitmask. The function
1207 returns `SOAP_OK` (zero) on success or an error if the string is not a valid
1208 enumeration name.
1209 
1210 🔝 [Back to table of contents](#)
1211 
1212 Numerical types {#toxsd5}
1213 ---------------
1214 
1215 Integer and floating point types are mapped to the equivalent built-in XSD
1216 types with the same sign and bit width.
1217 
1218 The `size_t` type is transient (not serializable) because its width is platform
1219 dependent. We recommend to use `uint64_t` instead.
1220 
1221 The XML value space of integer types are their decimal representations without
1222 loss of precision.
1223 
1224 The XML value space of floating point types are their decimal representations.
1225 The decimal representations are formatted with the printf format string "%.9G"
1226 for floats and the printf format string "%.17lG" for double. To change the
1227 format strings, we can assign new strings to the following `struct soap`
1228 context members:
1229 
1230 ```cpp
1231 soap.float_format = "%g";
1232 soap.double_format = "%lg";
1233 soap.long_double_format = "%Lg";
1234 ```
1235 
1236 Note that decimal representations may result in a loss of precision of the
1237 least significant decimal. Therefore, the format strings that are used by
1238 default are sufficiently precise to avoid loss, but this may result in long
1239 decimal fractions in the XML value space.
1240 
1241 The `long double` extended floating point type requires a custom serializer:
1242 
1243 ```cpp
1244 #import "custom/long_double.h"
1245 ... use long double ...
1246 ```
1247 
1248 You can now use `long double`, which has a serializer that serializes this type
1249 as `xsd:decimal`. Compile and link your code with `custom/long_double.c`.
1250 
1251 The value space of floating point values includes the special values `INF`,
1252 `-INF`, and `NaN`. You can check a value for plus or minus infinity and
1253 not-a-number as follows:
1254 
1255 ```cpp
1256 soap_isinf(x) && x > 0 // is x INF?
1257 soap_isinf(x) && x < 0 // is x -INF?
1258 soap_isnan(x) // is x NaN?
1259 ```
1260 
1261 To assign these values, use:
1262 
1263 ```cpp
1264 // x is float // x is double, long double, or __float128
1265 x = FLT_PINFY; x = DBL_PINFTY;
1266 x = FLT_NINFY; x = DBL_NINFTY;
1267 x = FLT_NAN; x = DBL_NAN;
1268 ```
1269 
1270 If your system supports `__float128` then you can also use this 128 bit
1271 floating point type with a custom serializer:
1272 
1273 ```cpp
1274 #import "custom/float128.h"
1275 ... use xsd__decimal ...
1276 ```
1277 
1278 Then use the `xsd__decimal` alias of `__float128`, which has a serializer. Do
1279 not use `__float128` directly, which is transient (not serializable).
1280 
1281 To check for `INF`, `-INF`, and `NaN` of a `__float128` value use:
1282 
1283 ```cpp
1284 isinfq(x) && x > 0 // is x INF?
1285 isinfq(x) && x < 0 // is x -INF?
1286 isnanq(x) // is x NaN?
1287 ```
1288 
1289 The range of a typedef-defined numerical type can be restricted using the range
1290 `:` operator with inclusive lower and upper bounds. For example:
1291 
1292 ```cpp
1293 typedef int ns__narrow -10 : 10;
1294 ```
1295 
1296 This maps to a simpleType restriction of `xsd:int` in the soapcpp2-generated
1297 schema:
1298 
1299 <div class="alt">
1300 ```xml
1301 <simpleType name="narrow">
1302  <restriction base="xsd:int">
1303  <minInclusive value="-10"/>
1304  <maxInclusive value="10"/>
1305  </restriction>
1306 </simpleType>
1307 ```
1308 </div>
1309 
1310 The lower and upper bound of a range are optional. When omitted, values are
1311 not bound from below or from above, respectively.
1312 
1313 The range of a floating point typedef-defined type can be restricted within
1314 floating point constant bounds.
1315 
1316 Also with a floating point typedef a printf format pattern can be given of the
1317 form `"%[width][.precision]f"` to format decimal values using the given width
1318 and precision fields:
1319 
1320 ```cpp
1321 typedef float ns__PH "%5.2f" 0.0 : 14.0;
1322 ```
1323 
1324 This maps to a simpleType restriction of `xsd:float` in the soapcpp2-generated
1325 schema:
1326 
1327 <div class="alt">
1328 ```xml
1329 <simpleType name="PH">
1330  <restriction base="xsd:float">
1331  <totalDigits value="5"/>
1332  <fractionDigits value="2"/>
1333  <minInclusive value="0"/>
1334  <maxInclusive value="14"/>
1335  </restriction>
1336 </simpleType>
1337 ```
1338 </div>
1339 
1340 For exclusive bounds, we use the `<` operator instead of the `:` range
1341 operator:
1342 
1343 ```cpp
1344 typedef float ns__epsilon 0.0 < 1.0;
1345 ```
1346 
1347 Values `eps` of `ns__epsilon` are restricted between `0.0 < eps < 1.0`.
1348 
1349 This maps to a simpleType restriction of `xsd:float` in the soapcpp2-generated
1350 schema:
1351 
1352 <div class="alt">
1353 ```xml
1354 <simpleType name="epsilon">
1355  <restriction base="xsd:float">
1356  <minExclusive value="0"/>
1357  <maxExclusive value="1"/>
1358  </restriction>
1359 </simpleType>
1360 ```
1361 </div>
1362 
1363 To make just one of the bounds exclusive, while keeping the other bound
1364 inclusive, we add a `<` on the left or on the right side of the range ':'
1365 operator. For example:
1366 
1367 ```cpp
1368 typedef float ns__pos 0.0 < : ; // 0.0 < pos
1369 typedef float ns__neg : < 0.0 ; // neg < 0.0
1370 ```
1371 
1372 It is valid to make both left and right side exclusive with `< : <` which is in
1373 fact identical to the exlusive range `<` operator:
1374 
1375 ```cpp
1376 typedef float ns__epsilon 0.0 < : < 1.0; // 0.0 < eps < 1.0
1377 ```
1378 
1379 It helps to think of the `:` as a placeholder of the value between the two
1380 bounds, which is easier to memorize than the shorthand forms of bounds from
1381 which the `:` is removed:
1382 
1383 | Bounds | Validation Check | Shorthand |
1384 | ---------- | ---------------- | --------- |
1385 | 1 : | 1 <= x | 1 |
1386 | 1 : 10 | 1 <= x <= 10 | |
1387 | : 10 | x <= 10 | |
1388 | 1 < : < 10 | 1 < x < 10 | 1 < 10 |
1389 | 1 : < 10 | 1 <= x < 10 | |
1390 | : < 10 | x < 10 | < 10 |
1391 | 1 < : | 1 < x | 1 < |
1392 | 1 < : 10 | 1 < x <= 10 | |
1393 
1394 Besides `float`, also `double` and `long double` values can be restricted. For
1395 example, consider a nonzero probability extended floating point precision type:
1396 
1397 ```cpp
1398 #import "custom/long_double.h"
1399 typedef long double ns__probability "%16Lg" 0.0 < : 1.0;
1400 ```
1401 
1402 Value range restrictions are validated by the parser for all inbound XML data.
1403 A type fault `SOAP_TYPE` will be thrown by the deserializer if the value is out
1404 of range.
1405 
1406 Finally, if your system supports `__int128_t` then you can also use this 128
1407 bit integer type with a custom serializer:
1408 
1409 ```cpp
1410 #import "custom/int128.h"
1411 ... use xsd__integer ...
1412 ```
1413 
1414 Use the `xsd__integer` alias of `__int128_t`, which has a serializer. Do not
1415 use `__int128_t` directly, which is transient (not serializable).
1416 
1417 To convert numeric values to a string, we use the auto-generated function for
1418 numeric type `T`:
1419 
1420 ```cpp
1421 const char *soap_T2s(struct soap*, T val)
1422 ```
1423 
1424 For numeric types `T`, the string returned is stored in an internal buffer of
1425 the current `soap` context, so you MUST copy it to keep it from being
1426 overwritten. For example, use `char *soap_strdup(struct soap*, const char*)`.
1427 
1428 To convert a string to a numeric value, we use the auto-generated function
1429 
1430 ```cpp
1431 int soap_s2T(struct soap*, const char *str, T *val)
1432 ```
1433 
1434 where `T` is for example `int`, `LONG64`, `float`, `decimal` (the custom
1435 serializer name of `long double`) or `xsd__integer` (the custom serializer name
1436 of `__int128_t`). The function `soap_s2T` returns `SOAP_OK` on success or an
1437 error when the value is not numeric. For floating point types, "INF", "-INF"
1438 and "NaN" are valid strings to convert to numbers.
1439 
1440 🔝 [Back to table of contents](#)
1441 
1442 String types {#toxsd6}
1443 ------------
1444 
1445 String types are mapped to the built-in `xsd:string` and `xsd:QName` XSD types.
1446 
1447 The wide strings `wchar_t*` and `std::wstring` may contain Unicode that is
1448 preserved in the XML value space.
1449 
1450 Strings `char*` and `std::string` can only contain extended Latin, but we can
1451 store UTF-8 content that is preserved in the XML value space when the `struct
1452 soap` context is initialized with the flag `SOAP_C_UTFSTRING`.
1453 
1454 @warning Beware that many XML 1.0 parsers reject all control characters (those
1455 between `#x1` and `#x1F`) except for `#x9`, `#xA`, and `#xD`. With the
1456 newer XML 1.1 version parsers (including gSOAP) you should be fine.
1457 
1458 The length of a string of a typedef-defined string type can be restricted:
1459 
1460 ```cpp
1461 typedef std::string ns__password 6 : 16;
1462 ```
1463 
1464 which maps to a simpleType restriction of `xsd:string` in the soapcpp2-generated
1465 schema:
1466 
1467 <div class="alt">
1468 ```xml
1469 <simpleType name="password">
1470  <restriction base="xsd:string">
1471  <minLength value="6"/>
1472  <maxLength value="16"/>
1473  </restriction>
1474 </simpleType>
1475 ```
1476 </div>
1477 
1478 String length restrictions are validated by the parser for inbound XML data.
1479 A value length fault `SOAP_LENGTH` will be thrown by the deserializer if the
1480 string is too long or too short.
1481 
1482 In addition, an XSD regex pattern restriction can be associated with a string
1483 typedef:
1484 
1485 ```cpp
1486 typedef std::string ns__password "([a-zA-Z]|[0-9]|-)+" 6 : 16;
1487 ```
1488 
1489 which maps to a simpleType restriction of `xsd:string` in the soapcpp2-generated
1490 schema:
1491 
1492 <div class="alt">
1493 ```xml
1494 <simpleType name="password">
1495  <restriction base="xsd:string">
1496  <pattern value="([a-zA-Z0-9]|-)+"/>
1497  <minLength value="6"/>
1498  <maxLength value="16"/>
1499  </restriction>
1500 </simpleType>
1501 ```
1502 </div>
1503 
1504 Pattern restrictions are validated by the parser for inbound XML data only if
1505 the `soap::fsvalidate` and `soap::fwvalidate` callbacks are defined, see the
1506 [gSOAP user guide.](http://www.genivia.com/doc/soapdoc2.html)
1507 
1508 Exclusive length bounds can be used with strings:
1509 
1510 ```cpp
1511 typedef std::string ns__string255 : < 256; // same as 0 : 255
1512 ```
1513 
1514 Fixed-size strings (`char[N]`) are rare occurrences in the wild, but apparently
1515 still used in some projects to store strings. To facilitate fixed-size string
1516 serialization, use soapcpp2 option `-b`. For example:
1517 
1518 ```cpp
1519 typedef char ns__buffer[10]; // requires soapcpp2 option -b
1520 ```
1521 
1522 which maps to a simpleType restriction of `xsd:string` in the soapcpp2-generated
1523 schema:
1524 
1525 <div class="alt">
1526 ```xml
1527 <simpleType name="buffer">
1528  <restriction base="xsd:string">
1529  <maxLength value="9"/>
1530  </restriction>
1531 </simpleType>
1532 ```
1533 </div>
1534 
1535 Note that fixed-size strings MUST contain NUL-terminated text and SHOULD NOT
1536 contain raw binary data. Also, the length limitation is more restrictive for
1537 UTF-8 content (enabled with the `SOAP_C_UTFSTRING`) that requires multibyte
1538 character encodings. As a consequence, UTF-8 content may be truncated to fit.
1539 
1540 Note that raw binary data can be stored in a `xsd__base64Binary` or
1541 `xsd__hexBinary` structure, or transmitted as a MIME attachment.
1542 
1543 The built-in `_QName` type is a regular C string type (`char*`) that maps to
1544 `xsd:QName` but has the added advantage that it holds normalized qualified names.
1545 There are actually two forms of normalized QName content, to ensure any QName
1546 is represented accurately and uniquely:
1547 
1548 ```cpp
1549 "prefix:name"
1550 "\"URI\":name"
1551 ```
1552 
1553 The first form of string is used when the prefix (and the binding URI) is
1554 defined in the namespace table and is bound to a URI (see the .nsmap file).
1555 The second form is used when the URI is not defined in the namespace table and
1556 therefore no prefix is available to bind and normalize the URI to.
1557 
1558 A `_QName` string may contain a sequence of space-separated QName values, not
1559 just one, and all QName values are normalized to the format shown above.
1560 
1561 To define a `std::string` base type for `xsd:QName`, we use a typedef:
1562 
1563 ```cpp
1564 typedef std::string xsd__QName;
1565 ```
1566 
1567 The `xsd__QName` string content is normalized, just as with the `_QName`
1568 normalization.
1569 
1570 To serialize strings that contain literal XML content to be reproduced in the
1571 XML value space, use the built-in `_XML` string type, which is a regular C
1572 string type (`char*`) that maps to plain XML CDATA.
1573 
1574 To define a `std::string` base type for literal XML content, use a typedef:
1575 
1576 ```cpp
1577 typedef std::string XML;
1578 ```
1579 
1580 Strings can hold any of the values of the XSD built-in primitive types. We can
1581 use a string typedef to declare the use of the string type as a XSD built-in
1582 type:
1583 
1584 ```cpp
1585 typedef std::string xsd__token;
1586 ```
1587 
1588 You MUST ensure that the string values we populate in this type conform to the
1589 XML standard, which in case of `xsd:token` is the lexical and value spaces of
1590 `xsd:token` are the sets of all strings after whitespace replacement of any
1591 occurrence of `#x9`, `#xA` , and `#xD` by `#x20` and collapsing.
1592 
1593 As of version 2.8.49, the gSOAP parser will automatically collapse or replace
1594 the white space content when receiving data for XSD types that require white
1595 space collapsed or replaced. This normalization is applied to strings
1596 directly. The decision to collapse or replace is based on the `typedef` name
1597 corresponding to the built-in string-based XSD type.
1598 
1599 To copy `char*` or `wchar_t*` strings with a context that manages the allocated
1600 memory, use functions
1601 
1602 ```cpp
1603 char *soap_strdup(struct soap*, const char*)
1604 wchar_t *soap_wstrdup(struct soap*, const wchar_t*)
1605 ```
1606 
1607 To convert a wide string to a UTF-8 encoded string, use function
1608 
1609 ```cpp
1610 const char* SOAP_FMAC2 soap_wchar2s(struct soap*, const wchar_t *s)
1611 ```
1612 
1613 The function allocates and returns a string, with its memory being managed by
1614 the context.
1615 
1616 To convert a UTF-8 encoded string to a wide string, use function
1617 
1618 ```cpp
1619 int soap_s2wchar(struct soap*, const char *from, wchar_t **to, long minlen, long maxlen)
1620 ```
1621 
1622 where `to` is set to point to an allocated `wchar_t*` string. Pass `-1` for
1623 `minlen` and `maxlen` to ignore length constraints on the target string. The
1624 function returns `SOAP_OK` or an error when the length constraints are not met.
1625 
1626 🔝 [Back to table of contents](#)
1627 
1628 Date and time types {#toxsd7}
1629 -------------------
1630 
1631 The C/C++ `time_t` type is mapped to the built-in `xsd:dateTime` XSD type that
1632 represents a date and time within a time zone (typically UTC).
1633 
1634 The XML value space contains ISO 8601 Gregorian time instances of the form
1635 `[-]CCYY-MM-DDThh:mm:ss.sss[Z|(+|-)hh:mm]`, where `Z` is the UTC time zone
1636 or a time zone offset `(+|-)hh:mm]` from UTC is used.
1637 
1638 A `time_t` value is considered and represented in UTC by the serializer.
1639 
1640 Because the `time_t` value range is restricted to dates after 01/01/1970 and
1641 before 2038 assuming `time_t` is a `long` 32 bit, care must be taken to ensure
1642 the range of `xsd:dateTime` values in XML exchanges do not exceed the `time_t`
1643 range.
1644 
1645 This restriction does not hold for `struct tm` (`<time.h>`), which we can use
1646 to store and exchange a date and time in UTC without date range restrictions.
1647 The serializer uses the `struct tm` members directly for the XML value space of
1648 `xsd:dateTime`:
1649 
1650 ```cpp
1651 struct tm
1652 {
1653  int tm_sec; // seconds (0 - 60)
1654  int tm_min; // minutes (0 - 59)
1655  int tm_hour; // hours (0 - 23)
1656  int tm_mday; // day of month (1 - 31)
1657  int tm_mon; // month of year (0 - 11)
1658  int tm_year; // year - 1900
1659  int tm_wday; // day of week (Sunday = 0) (NOT USED)
1660  int tm_yday; // day of year (0 - 365) (NOT USED)
1661  int tm_isdst; // is summer time in effect?
1662  char* tm_zone; // abbreviation of timezone (NOT USED)
1663 };
1664 ```
1665 
1666 You will lose the day of the week information. It is always Sunday
1667 (`tm_wday=0`) and the day of the year is not set either. The time zone is UTC.
1668 
1669 This `struct tm` type is mapped to the built-in `xsd:dateTime` XSD type and
1670 serialized with the custom serializer `custom/struct_tm.h` that declares a
1671 `xsd__dateTime` type:
1672 
1673 ```cpp
1674 #import "custom/struct_tm.h" // import typedef struct tm xsd__dateTime;
1675 ... use xsd__dateTime ...
1676 ```
1677 
1678 Compile and link your code with `custom/struct_tm.c`.
1679 
1680 The `struct timeval` (`<sys/time.h>`) type is mapped to the built-in
1681 `xsd:dateTime` XSD type and serialized with the custom serializer
1682 `custom/struct_timeval.h` that declares a `xsd__dateTime` type:
1683 
1684 ```cpp
1685 #import "custom/struct_timeval.h" // import typedef struct timeval xsd__dateTime;
1686 ... use xsd__dateTime ...
1687 ```
1688 
1689 Compile and link your code with `custom/struct_timeval.c`.
1690 
1691 Note that the same value range restrictions apply to `struct timeval` as they
1692 apply to `time_t`. The added benefit of `struct timeval` is the addition of
1693 a microsecond-precise clock:
1694 
1695 ```cpp
1696 struct timeval
1697 {
1698  time_t tv_sec; // seconds since Jan. 1, 1970
1699  suseconds_t tv_usec; // and microseconds
1700 };
1701 ```
1702 
1703 A C++11 `std::chrono::system_clock::time_point` type is mapped to the built-in
1704 `xsd:dateTime` XSD type and serialized with the custom serializer
1705 `custom/chrono_time_point.h` that declares a `xsd__dateTime` type:
1706 
1707 ```cpp
1708 #import "custom/chrono_time_point.h" // import typedef std::chrono::system_clock::time_point xsd__dateTime;
1709 ... use xsd__dateTime ...
1710 ```
1711 
1712 Compile and link your code with `custom/chrono_time_point.cpp`.
1713 
1714 The `struct tm` type is mapped to the built-in `xsd:date` XSD type and serialized
1715 with the custom serializer `custom/struct_tm_date.h` that declares a
1716 `xsd__date` type:
1717 
1718 ```cpp
1719 #import "custom/struct_tm_date.h" // import typedef struct tm xsd__date;
1720 ... use xsd__date ...
1721 ```
1722 
1723 Compile and link your code with `custom/struct_tm_date.c`.
1724 
1725 The XML value space of `xsd:date` are Gregorian calendar dates of the form
1726 `[-]CCYY-MM-DD[Z|(+|-)hh:mm]` with a time zone.
1727 
1728 The serializer ignores the time part and the deserializer only populates the
1729 date part of the struct, setting the time to 00:00:00. There is no unreasonable
1730 limit on the date range because the year field is stored as an integer (`int`).
1731 
1732 An `unsigned long long` (`ULONG64` or `uint64_t`) type that contains a 24 hour
1733 time in microseconds UTC is mapped to the built-in `xsd:time` XSD type and
1734 serialized with the custom serializer `custom/long_time.h` that declares a
1735 `xsd__time` type:
1736 
1737 ```cpp
1738 #import "custom/long_time.h" // import typedef unsigned long long xsd__time;
1739 ... use xsd__time ...
1740 ```
1741 
1742 Compile and link your code with `custom/long_time.c`.
1743 
1744 This type represents `00:00:00.000000` to `23:59:59.999999`, from 0 to an
1745 upper bound of 86,399,999,999. A microsecond resolution means that a 1 second
1746 increment requires an increment of 1,000,000 in the integer value.
1747 
1748 The XML value space of `xsd:time` are points in time recurring each day of the
1749 form `hh:mm:ss.sss[Z|(+|-)hh:mm]`, where `Z` is the UTC time zone or a time
1750 zone offset from UTC is used. The `xsd__time` value is always considered and
1751 represented in UTC by the serializer.
1752 
1753 To convert date and/or time values to a string, we use the auto-generated
1754 function for type `T`:
1755 
1756 ```cpp
1757 const char *soap_T2s(struct soap*, T val)
1758 ```
1759 
1760 For date and time types `T`, the string returned is stored in an internal
1761 buffer of the current `soap` context, so you MUST copy it to keep it from being
1762 overwritten. For example, use `char *soap_strdup(struct soap*, const char*)`.
1763 
1764 To convert a string to a date/time value, we use the auto-generated function
1765 
1766 ```cpp
1767 int soap_s2T(struct soap*, const char *str, T *val)
1768 ```
1769 
1770 where `T` is for example `dateTime` (for `time_t`), `xsd__dateTime` (for
1771 `struct tm`, `struct timeval`, or `std::chrono::system_clock::time_point`).
1772 The function `soap_s2T` returns `SOAP_OK` on success or an error when the value
1773 is not a date/time.
1774 
1775 🔝 [Back to table of contents](#)
1776 
1777 Time duration types {#toxsd8}
1778 -------------------
1779 
1780 The XML value space of `xsd:duration` are values of the form `PnYnMnDTnHnMnS`
1781 where the capital letters are delimiters. Delimiters may be omitted when the
1782 corresponding member is not used.
1783 
1784 A `long long` (`LONG64` or `int64_t`) type that contains a duration (time
1785 lapse) in milliseconds is mapped to the built-in `xsd:duration` XSD type and
1786 serialized with the custom serializer `custom/duration.h` that declares a
1787 `xsd__duration` type:
1788 
1789 ```cpp
1790 #import "custom/duration.h" // import typedef long long xsd__duration;
1791 ... use xsd__duration ...
1792 ```
1793 
1794 Compile and link your code with `custom/duration.c`.
1795 
1796 The duration type `xsd__duration` can represent 106,751,991,167 days forward
1797 and backward with millisecond precision.
1798 
1799 Durations that exceed a month are always output in days, rather than months to
1800 avoid days-per-month conversion inacurracies.
1801 
1802 Durations that are received in years and months instead of total number of days
1803 from a reference point are not well defined, since there is no accepted
1804 reference time point (it may or may not be the current time). The decoder
1805 simple assumes that there are 30 days per month. For example, conversion of
1806 "P4M" gives 120 days. Therefore, the durations "P4M" and "P120D" are assumed
1807 to be identical, which is not necessarily true depending on the reference point
1808 in time.
1809 
1810 Rescaling of the duration value by may be needed when adding the duration value
1811 to a `time_t` value, because `time_t` may or may not have a seconds resolution,
1812 depending on the platform and possible changes to `time_t`.
1813 
1814 Rescaling is done automatically when you add a C++11 `std::chrono::nanoseconds`
1815 value to a `std::chrono::system_clock::time_point` value. To use
1816 `std::chrono::nanoseconds` as `xsd:duration`:
1817 
1818 ```cpp
1819 #import "custom/chrono_duration.h" // import typedef std::chrono::duration xsd__duration;
1820 ... use xsd__duration ...
1821 ```
1822 
1823 Compile and link your code with `custom/chrono_duration.cpp`.
1824 
1825 This type can represent 384,307,168 days (2^63 nanoseconds) forwards and
1826 backwards in time in increments of 1 ns (1/1000000000 second).
1827 
1828 The same observations with respect to receiving durations in years and months
1829 apply to this serializer's decoder.
1830 
1831 To convert duration values to a string, we use the auto-generated function
1832 
1833 ```cpp
1834 const char *soap_xsd__duration2s(struct soap*, xsd__duration val)
1835 ```
1836 
1837 The string returned is stored in an internal buffer, so you MUST copy it to
1838 keep it from being overwritten, Use `soap_strdup(struct soap*, const char*)`
1839 for example to copy this string.
1840 
1841 To convert a string to a duration value, we use the auto-generated function
1842 
1843 ```cpp
1844 int soap_s2xsd__dateTime(struct soap*, const char *str, xsd__dateTime *val)
1845 ```
1846 
1847 The function returns `SOAP_OK` on success or an error when the value is not a
1848 duration.
1849 
1850 🔝 [Back to table of contents](#)
1851 
1852 Classes and structs {#toxsd9}
1853 -------------------
1854 
1855 Classes and structs are mapped to XSD complexTypes. The XML value space
1856 consists of XML elements with attributes and subelements, possibly constrained
1857 by XML schema validation rules that enforce element and attribute occurrence
1858 contraints, numerical value range constraints, and string length and pattern
1859 constraints.
1860 
1861 Classes that are declared with the gSOAP tools are limited to single
1862 inheritence only. Structs cannot be inherited.
1863 
1864 The class and struct name is bound to an XML namespace by means of the prefix
1865 naming convention or by using [colon notation](#toxsd1):
1866 
1867 ```cpp
1868 //gsoap ns schema namespace: urn:types
1869 class ns__record
1870 {
1871  public:
1872  std::string name;
1873  uint64_t SSN;
1874  ns__record *spouse;
1875  ns__record();
1876  ~ns__record();
1877  protected:
1878  struct soap *soap;
1879 };
1880 ```
1881 
1882 In the example above, we also added a context pointer to the `struct soap` that
1883 manages this instance. It is set when the instance is created in the engine's
1884 context, for example when deserialized and populated by the engine.
1885 
1886 The class maps to a complexType in the soapcpp2-generated schema:
1887 
1888 <div class="alt">
1889 ```xml
1890 <complexType name="record">
1891  <sequence>
1892  <element name="name" type="xsd:string" minOccurs="1" maxOccurs="1"/>
1893  <element name="SSN" type="xsd:unsignedLong" minOccurs="1" maxOccurs="1"/>
1894  <element name="spouse" type="ns:record" minOccurs="0" maxOccurs="1" nillable="true"/>
1895  </sequence>
1896 </complexType>
1897 ```
1898 </div>
1899 
1900 🔝 [Back to table of contents](#)
1901 
1902 ### Serializable versus transient types and data members {#toxsd9-1}
1903 
1904 Public data members of a class or struct are serialized. Private and protected
1905 members are transient and not serializable.
1906 
1907 Also `const` and `static` members are not serializable, with the exception of
1908 `const char*` and `const wchar_t*`. Types and specific class/struct members
1909 can also be made transient with the `extern` qualifier:
1910 
1911 ```cpp
1912 extern class std::ostream; // declare 'std::ostream' transient
1913 class ns__record
1914 {
1915  public:
1916  extern int num; // not serialized
1917  std::ostream out; // not serialized
1918  static const int MAX = 1024; // not serialized
1919 };
1920 ```
1921 
1922 By declaring `std::ostream` transient with `extern` you can use this type
1923 wherever you need it without soapcpp2 complaining that this class is not
1924 defined.
1925 
1926 🔝 [Back to table of contents](#)
1927 
1928 ### Volatile classes and structs {#toxsd9-2}
1929 
1930 Classes and structs can be declared `volatile` with the gSOAP tools. This means
1931 that they are already declared elsewhere in your project's source code and you
1932 do not want soapcpp2 to generate code with a second declaration of these types.
1933 
1934 For example, `struct tm` is declared in `<time.h>`. You can make it serializable
1935 and include a partial list of data members that you want to serialize:
1936 
1937 ```cpp
1938 volatile struct tm
1939 {
1940  int tm_sec; // seconds (0 - 60)
1941  int tm_min; // minutes (0 - 59)
1942  int tm_hour; // hours (0 - 23)
1943  int tm_mday; // day of month (1 - 31)
1944  int tm_mon; // month of year (0 - 11)
1945  int tm_year; // year - 1900
1946 };
1947 ```
1948 
1949 You can declare classes and structs `volatile` for any such types you want to
1950 serialize by only providing the public data members you want to serialize.
1951 
1952 In addition, [colon notation](#toxsd2) is a simple and effective way to bind an
1953 existing class or struct to a schema. For example, you can change the `tm` name
1954 as follows without affecting the code that uses `struct tm` generated by
1955 soapcpp2:
1956 
1957 ```cpp
1958 volatile struct ns:tm { ... }
1959 ```
1960 
1961 This struct maps to a complexType in the soapcpp2-generated schema:
1962 
1963 <div class="alt">
1964 ```xml
1965 <complexType name="tm">
1966  <sequence>
1967  <element name="tm-sec" type="xsd:int" minOccurs="1" maxOccurs="1"/>
1968  <element name="tm-min" type="xsd:int" minOccurs="1" maxOccurs="1"/>
1969  <element name="tm-hour" type="xsd:int" minOccurs="1" maxOccurs="1"/>
1970  <element name="tm-mday" type="xsd:int" minOccurs="1" maxOccurs="1"/>
1971  <element name="tm-mon" type="xsd:int" minOccurs="1" maxOccurs="1"/>
1972  <element name="tm-year" type="xsd:int" minOccurs="1" maxOccurs="1"/>
1973  </sequence>
1974 </complexType>
1975 ```
1976 </div>
1977 
1978 🔝 [Back to table of contents](#)
1979 
1980 ### Mutable classes and structs {#toxsd9-3}
1981 
1982 Classes and structs can be declared `mutable` with the gSOAP tools. This means
1983 that their definition can be spread out over the source code. This promotes the
1984 concept of a class or struct as a *row of named values*, also known as a *named
1985 tuple*, that can be extended at compile time in your source code with additional
1986 members. Because these types differ from the traditional object-oriented
1987 principles and design concepts of classes and objects, constructors and
1988 destructors cannot be defined (also because we cannot guarantee merging these
1989 into one such that all members will be initialized). A default constructor,
1990 copy constructor, assignment operation, and destructor will be assigned
1991 automatically by soapcpp2.
1992 
1993 ```cpp
1994 mutable struct ns__tuple
1995 {
1996  @std::string id;
1997 };
1998 
1999 mutable struct ns__tuple
2000 {
2001  std::string name;
2002  std::string value;
2003 };
2004 ```
2005 
2006 The members are collected into one definition generated by soapcpp2. Members
2007 may be repeated from one definition to another, but only if their associated
2008 types are identical. So, for example, a third extension with a `value` member
2009 with a different type fails:
2010 
2011 ```cpp
2012 mutable struct ns__tuple
2013 {
2014  float value; // BAD: value is already declared std::string
2015 };
2016 ```
2017 
2018 The `mutable` concept has proven to be very useful when declaring and
2019 collecting SOAP Headers for multiple services, which are collected into one
2020 `struct SOAP_ENV__Header` by the soapcpp2 tool.
2021 
2022 🔝 [Back to table of contents](#)
2023 
2024 ### Default and fixed member values {#toxsd9-4}
2025 
2026 Class and struct data members in C and C++ may be declared with an optional
2027 default initialization value that is provided "inline" with the declaration of
2028 the member:
2029 
2030 ```cpp
2031 class ns__record
2032 {
2033  public:
2034  std::string name = "Joe";
2035  ...
2036 };
2037 ```
2038 
2039 Alternatively, use C++11 default initialization syntax:
2040 
2041 ```cpp
2042 class ns__record
2043 {
2044  public:
2045  std::string name { "Joe" };
2046  ...
2047 };
2048 ```
2049 
2050 These initializations are made by the default constructor that is added by
2051 soapcpp2 to each class and struct (in C++ only). A constructor is only added
2052 when a default constructor is not already defined with the class declaration.
2053 
2054 You can explicitly (re)initialize an object with these initial values by using
2055 the soapcpp2 auto-generated functions:
2056 
2057 - `void T::soap_default(struct soap*)` for `class T` (C++ only)
2058 - `void soap_default_T(struct soap*, T*)` for `struct T` (C and C++).
2059 
2060 Default value initializations can be provided for members that have primitive
2061 types (`bool`, `enum`, `time_t`, numeric and string types).
2062 
2063 Default value initializations of pointer members is permitted, but the effect
2064 is different. To conform to XML schema validation, an attribute member that is
2065 a pointer to a primitive type will be assigned the default value when parsed
2066 from XML. An element member that is a pointer to a primitive type will be
2067 assigned when the element is empty when parsed from XML.
2068 
2069 As of gSOAP 2.8.48 and greater, a fixed value can be assigned with a `==`. A
2070 fixed value is also verified by the parser's validator.
2071 
2072 Default and fixed values for members with or without pointers are best
2073 explained with the following two example fragments.
2074 
2075 A record class (can be a struct in C) with default values for attributes and
2076 elements is declared as follows:
2077 
2078 ```cpp
2079 class ns__record_with_default
2080 {
2081  public:
2082  @std::string a = "A"; // optional XML attribute with default value "A"
2083  @std::string b 1 = "B"; // required XML attribute with default value "B"
2084  @std::string *c = "C"; // optional XML attribute with default value "C"
2085  std::string d 0 = "D"; // optional XML element with default value "D"
2086  std::string e = "E"; // required XML element with default value "E"
2087  std::string *f = "F"; // optional XML element with default value "F"
2088  ...
2089 };
2090 ```
2091 
2092 Note that attributes are optional unless marked as required with the occurrence
2093 constraint `1`. Elements are required unless the member type is a pointer or
2094 if the member is marked optional with occurrence constraint `0`.
2095 
2096 Instead of default values, fixed values indicate that the attribute or element
2097 must contain that value, and only that value, when provided in XML. A fixed
2098 value is specified with a `==`.
2099 
2100 A record class (can be a struct in C) with fixed values for attributes and
2101 elements is declared as follows:
2102 
2103 ```cpp
2104 class ns__record_with_fixed
2105 {
2106  public:
2107  @std::string g == "G"; // optional XML attribute with fixed value "G"
2108  @std::string h 1 == "H"; // required XML attribute with fixed value "H"
2109  @std::string *i == "I"; // optional XML attribute with fixed value "I"
2110  std::string j 0 == "J"; // optional XML element with fixed value "J"
2111  std::string k == "K"; // required XML element with fixed value "K"
2112  std::string *l == "L"; // optional XML element with fixed value "L"
2113  ...
2114 };
2115 ```
2116 
2117 The XML schema validation rules for the two example classes above are as
2118 follows:
2119 
2120 Member | Notes
2121 ------ | ---------------------------------------------------------------------
2122 `a` | attribute may appear once; if it does not appear its value is "A", otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns the default value "A")
2123 `b` | has no effect when parsing XML (but note: instantiating `ns__record_with_default` assigns the default value "B")
2124 `c` | attribute may appear once; if it does not appear its value is "C", otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns NULL)
2125 `d` | element may appear once; if it does not appear or if it is empty, its value is "D"; otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns the default value "D")
2126 `e` | has no effect when parsing XML (but note: instantiating `ns__record_with_default` assigns the default value "E")
2127 `f` | element may appear once; if it does not appear it is not provided; if it does appear and it is empty, its value is "F"; otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns NULL)
2128 `g` | attribute may appear once; if it does not appear its value is "G", if it does not appear its value is "G" (also note: instantiating `ns__record_with_fixed` assigns the fixed value "G")
2129 `h` | attribute must appear once, its value must be "H" (also note: instantiating `ns__record_with_fixed` assigns the fixed value "H")
2130 `i` | attribute may appear once; if it does not appear its value is "I", if it does not appear its value is "I" (also note: instantiating `ns__record_with_fixed` assigns NULL)
2131 `j` | element may appear once, if it does not appear it is not provided; if it does appear and it is empty, its value is "J"; if it does appear and it is not empty, its value must be "J" (also note: instantiating `ns__record_with_fixed` assigns the fixed value "J")
2132 `k` | element must appear once, its value must be "K" (also note: instantiating `ns__record_with_fixed` assigns the fixed value "K")
2133 `l` | element may appear once, if it does not appear it is not provided; if it does appear and it is empty, its value is "J"; if it does appear and it is not empty, its value must be "J" (also note: instantiating `ns__record_with_fixed` assigns NULL)
2134 
2135 @see Section [operations on classes and structs](#toxsd9-13).
2136 
2137 🔝 [Back to table of contents](#)
2138 
2139 ### Attribute members and backtick XML tags {#toxsd9-5}
2140 
2141 Class and struct data members are declared as XML attributes by annotating
2142 their type with a `@` qualifier:
2143 
2144 ```cpp
2145 class ns__record
2146 {
2147  public:
2148  @std::string name;
2149  @uint64_t SSN;
2150  ns__record *spouse;
2151 };
2152 ```
2153 
2154 This class maps to a complexType in the soapcpp2-generated schema:
2155 
2156 <div class="alt">
2157 ```xml
2158 <complexType name="record">
2159  <sequence>
2160  <element name="spouse" type="ns:record" minOccurs="0" maxOccurs="1" nillable="true"/>
2161  </sequence>
2162  <attribute name="name" type="xsd:string" use="required"/>
2163  <attribute name="SSN" type="xsd:unsignedLong" use="required"/>
2164 </complexType>
2165 ```
2166 </div>
2167 
2168 An example XML instance of `ns__record` is:
2169 
2170 <div class="alt">
2171 ```xml
2172 <ns:record xmlns:ns="urn:types" name="Joe" SSN="1234567890">
2173  <spouse name="Jane" SSN="1987654320">
2174  </spouse>
2175 </ns:record>
2176 ```
2177 </div>
2178 
2179 Attribute data members are restricted to primitive types (`bool`, `enum`,
2180 `time_t`, numeric and string types), `xsd__hexBinary`, `xsd__base64Binary`, and
2181 custom serializers, such as `xsd__dateTime`. Custom serializers for types that
2182 may be used as attributes MUST define `soap_s2T` and `soap_T2s` functions that
2183 convert values of type `T` to strings and back.
2184 
2185 Attribute data members can be pointers and smart pointers to these types, which
2186 permits attributes to be optional.
2187 
2188 The XML tag name of a class/struct member is the name of the member with the
2189 usual XML tag translation, see [colon notation](#toxsd2).
2190 
2191 To override the standard translation of identifier names to XML tag names of
2192 attributes and elements, add the XML tag name in backticks (requires gSOAP
2193 2.8.30 and later versions):
2194 
2195 ```cpp
2196 class ns__record
2197 {
2198  public:
2199  @std::string name `full-name`;
2200  @uint64_t SSN `tax-id`;
2201  ns__record *spouse `married-to`;
2202 };
2203 ```
2204 
2205 This class maps to a complexType in the soapcpp2-generated schema:
2206 
2207 <div class="alt">
2208 ```xml
2209 <complexType name="record">
2210  <sequence>
2211  <element name="married-to" type="ns:record" minOccurs="0" maxOccurs="1" nillable="true"/>
2212  </sequence>
2213  <attribute name="full-name" type="xsd:string" use="required"/>
2214  <attribute name="tax-id" type="xsd:unsignedLong" use="required"/>
2215 </complexType>
2216 ```
2217 </div>
2218 
2219 An example XML instance of `ns__record` is:
2220 
2221 <div class="alt">
2222 ```xml
2223 <ns:record xmlns:ns="urn:types" full-name="Joe" tax-id="1234567890">
2224  <married-to full-name="Jane" tax-id="1987654320">
2225  </married-to>
2226 </ns:record>
2227 ```
2228 </div>
2229 
2230 A backtick XML tag name may contain any non-empty sequence of ASCII and UTF-8
2231 characters except white space and the backtick character. A backtick tag can
2232 be combined with member constraints and default member initializers:
2233 
2234  @uint64_t SSN `tax-id` 0:1 = 999;
2235 
2236 🔝 [Back to table of contents](#)
2237 
2238 ### Qualified and unqualified members {#toxsd9-6}
2239 
2240 Class, struct, and union data members are mapped to namespace qualified or
2241 unqualified tag names of local elements and attributes. If a data member has
2242 no prefix then the default form of qualification is applied based on the
2243 element/attribute form that is declared with the schema of the class, struct,
2244 or union type. If the member name has a namespace prefix by colon notation,
2245 then the prefix overrules the default (un)qualified form. Therefore,
2246 [colon notation](#toxsd2) is an effective mechanism to control qualification of
2247 tag names of individual members of classes, structs, and unions.
2248 
2249 The XML schema elementFormDefault and attributeFormDefault declarations control
2250 the tag name qualification of local elements and attributes, respectively.
2251 
2252 - "unqualified" indicates that local elements/attributes are not qualified with
2253  the namespace prefix.
2254 
2255 - "qualified" indicates that local elements/attributes must be qualified with
2256  the namespace prefix.
2257 
2258 Individual schema declarations of local elements and attributes may overrule
2259 this by using the form declaration in a schema and by using colon notation to
2260 add namespace prefixes to class, struct, and union members in the header file
2261 for soapcpp2.
2262 
2263 Consider for example an `ns__record` class in the `ns` namespace in which local
2264 elements are qualified and local attributes are unqualified by default:
2265 
2266 ```cpp
2267 //gsoap ns schema namespace: urn:types
2268 //gsoap ns schema elementForm: qualified
2269 //gsoap ns schema attributeForm: unqualified
2270 class ns__record
2271 {
2272  public:
2273  @std::string name;
2274  @uint64_t SSN;
2275  ns__record *spouse;
2276 };
2277 ```
2278 
2279 This class maps to a complexType in the soapcpp2-generated schema with
2280 targetNamespace "urn:types", elementFormDefault qualified and
2281 attributeFormDefault unqualified:
2282 
2283 <div class="alt">
2284 ```xml
2285 <schema targetNamespace="urn:types"
2286  ...
2287  elementFormDefault="qualified"
2288  attributeFormDefault="unqualified"
2289  ... >
2290  <complexType name="record">
2291  <sequence>
2292  <element name="spouse" type="ns:record" minOccurs="0" maxOccurs="1" nillable="true"/>
2293  </sequence>
2294  <attribute name="name" type="xsd:string" use="required"/>
2295  <attribute name="SSN" type="xsd:unsignedLong" use="required"/>
2296  </complexType>
2297 </schema>
2298 ```
2299 </div>
2300 
2301 An example XML instance of `ns__record` is:
2302 
2303 <div class="alt">
2304 ```xml
2305 <ns:record xmlns:ns="urn:types" name="Joe" SSN="1234567890">
2306  <ns:spouse> name="Jane" SSN="1987654320">
2307  </ns:spouse>
2308 </ns:record>
2309 ```
2310 </div>
2311 
2312 Note that the root element ns:record is qualified because it is a root element
2313 of the schema with target namespace "urn:types". Its local element ns:spouse
2314 is namespace qualified because the elementFormDefault of local elements is
2315 qualified. Attributes are unqualified.
2316 
2317 The default namespace (un)qualification of local elements and attributes can be
2318 overruled by adding a prefix to the member name by using colon notation:
2319 
2320 ```cpp
2321 //gsoap ns schema namespace: urn:types
2322 //gsoap ns schema elementForm: qualified
2323 //gsoap ns schema attributeForm: unqualified
2324 class ns__record
2325 {
2326  public:
2327  @std::string ns:name; // 'ns:' qualified
2328  @uint64_t SSN;
2329  ns__record *:spouse; // ':' unqualified (empty prefix)
2330 };
2331 ```
2332 
2333 The colon notation for member `ns:name` forces qualification of its attribute
2334 tag in XML. The colon notation for member `:spouse` removes qualification from
2335 its local element tag:
2336 
2337 <div class="alt">
2338 ```xml
2339 <schema targetNamespace="urn:types"
2340  ...
2341  elementFormDefault="unqualified"
2342  attributeFormDefault="unqualified"
2343  ... >
2344  <complexType name="record">
2345  <sequence>
2346  <element name="spouse" type="ns:record" minOccurs="0" maxOccurs="1" nillable="true" form="unqualified"/>
2347  </sequence>
2348  <attribute name="name" type="xsd:string" use="required" form="qualified"/>
2349  <attribute name="SSN" type="xsd:unsignedLong" use="required"/>
2350  </complexType>
2351 </schema>
2352 ```
2353 </div>
2354 
2355 XML instances of `ns__record` have unqualified spouse elements and qualified
2356 ns:name attributes:
2357 
2358 <div class="alt">
2359 ```xml
2360 <ns:record xmlns:ns="urn:types" ns:name="Joe" SSN="1234567890">
2361  <spouse> ns:name="Jane" SSN="1987654320">
2362  </spouse>
2363 </ns:record>
2364 ```
2365 </div>
2366 
2367 Note that data members can also be prefixed using the `prefix__name`
2368 convention. However, this has a different effect by referring to global (root)
2369 elements and attributes, see [document root element definitions](#toxsd9-7).
2370 
2371 [Backtick tag names](#toxsd9-5) can be used in place of the member name
2372 annotations and will achieve the same effect as described when these tag names
2373 are (un)qualified (requires gSOAP 2.8.30 and later versions).
2374 
2375 @note You must declare a target namespace with a `//gsoap ns schema namespace:`
2376 directive to enable the `elementForm` and `attributeForm` directives in order
2377 to generate valid schemas with soapcpp2. See [directives](#directives) for
2378 more details.
2379 
2380 🔝 [Back to table of contents](#)
2381 
2382 ### Defining document root elements {#toxsd9-7}
2383 
2384 To define and reference XML document root elements we use type names that start
2385 with an underscore:
2386 
2387 ```cpp
2388 class _ns__record
2389 ```
2390 
2391 Alternatively, we can use a typedef to define a document root element with a
2392 given type:
2393 
2394 ```cpp
2395 typedef ns__record _ns__record;
2396 ```
2397 
2398 This typedef maps to a global root element that is added to the
2399 soapcpp2-generated schema:
2400 
2401 <div class="alt">
2402 ```xml
2403 <element name="record" type="ns:record"/>
2404 ```
2405 </div>
2406 
2407 An example XML instance of `_ns__record` is:
2408 
2409 <div class="alt">
2410 ```xml
2411 <ns:record xmlns:ns="urn:types">
2412  <name>Joe</name>
2413  <SSN>1234567890</SSN>
2414  <spouse>
2415  <name>Jane</name>
2416  <SSN>1987654320</SSN>
2417  </spouse>
2418 </ns:record>
2419 ```
2420 </div>
2421 
2422 Global-level element/attribute definitions are also referenced and/or added to
2423 the generated schema when serializable data members reference these by their
2424 qualified name:
2425 
2426 ```cpp
2427 typedef std::string _ns__name 1 : 100;
2428 class _ns__record
2429 {
2430  public:
2431  @_QName xsi__type; // built-in XSD attribute xsi:type
2432  _ns__name ns__name; // ref to global ns:name element
2433  uint64_t SSN;
2434  _ns__record *spouse;
2435 };
2436 ```
2437 
2438 These types map to the following comonents in the soapcpp2-generated schema:
2439 
2440 <div class="alt">
2441 ```xml
2442 <simpleType name="name">
2443  <restriction base="xsd:string">
2444  <minLength value="1"/>
2445  <maxLength value="100"/>
2446  </restriction>
2447 </simpleType>
2448 <element name="name" type="ns:name"/>
2449 <complexType name="record">
2450  <sequence>
2451  <element ref="ns:name" minOccurs="1" maxOccurs="1"/>
2452  <element name="SSN" type="xsd:unsignedLong" minOccurs="1" maxOccurs="1"/>
2453  <element name="spouse" type="ns:record" minOccurs="0" maxOccurs="1" nillable="true"/>
2454  </sequence>
2455  <attribute ref="xsi:type" use="optional"/>
2456 </complexType>
2457 <element name="record" type="ns:record"/>
2458 ```
2459 </div>
2460 
2461 Use only use qualified member names when their types match the global-level
2462 element types that they refer to. For example:
2463 
2464 ```cpp
2465 typedef std::string _ns__name; // global element ns:name of type xsd:string
2466 class _ns__record
2467 {
2468  public:
2469  int ns__name; // BAD: global element ns:name is NOT type int
2470  _ns__record ns__record; // OK: ns:record is a global-level root element
2471  ...
2472 };
2473 ```
2474 
2475 Therefore, we recommend to use qualified member names only when necessary to
2476 refer to standard XSD elements and attributes, such as `xsi__type`, and
2477 `xsd__lang`.
2478 
2479 By contrast, colon notation has the desired effect to (un)qualify local tag
2480 names by overruling the default element/attribute namespace qualification, see
2481 [qualified and unqualified members](#toxsd9-6).
2482 
2483 As an alternative to prefixing member names, use the backtick tag (requires
2484 gSOAP 2.8.30 and later versions):
2485 
2486 ```cpp
2487 typedef std::string _ns__name 1 : 100;
2488 class _ns__record
2489 {
2490  public:
2491  @_QName t `xsi:type`; // built-in XSD attribute xsi:type
2492  _ns__name s `ns:name`; // ref to global ns:name element
2493  uint64_t SSN;
2494  _ns__record *spouse;
2495 };
2496 ```
2497 
2498 🔝 [Back to table of contents](#)
2499 
2500 ### (Smart) pointer members and their occurrence constraints {#toxsd9-8}
2501 
2502 A public pointer-typed data member is serialized by following its (smart)
2503 pointer(s) to the value pointed to. To serialize pointers to dynamic arrays of
2504 data, please see the next section on
2505 [container and array members and their occurrence constraints](#toxsd9-9).
2506 
2507 Pointers that are NULL and smart pointers that are empty are serialized to
2508 produce omitted element and attribute values, unless an element is required
2509 and is nillable.
2510 
2511 To control the occurrence requirements of pointer-based data members,
2512 occurrence constraints are associated with data members in the form of a range
2513 `minOccurs : maxOccurs`. For non-repeatable (meaning, not a container or array)
2514 data members, there are only three reasonable occurrence constraints:
2515 
2516 - `0:0` means that this element or attribute is prohibited.
2517 - `0:1` means that this element or attribute is optional.
2518 - `1:1` means that this element or attribute is required.
2519 
2520 Pointer-based data members have a default `0:1` occurrence constraint, making
2521 them optional, and their XML schema local element/attribute definition is
2522 marked as nillable. Non-pointer data members have a default `1:1` occurence
2523 constraint, making them required.
2524 
2525 A `nullptr` occurrence constraint may be applicable to required elements that
2526 are nillable pointer types, thus `nullptr 1:1`. This indicates that the
2527 element is nillable (can be `NULL` or `nullptr`). A pointer data member that
2528 is explicitly marked as required and nillable with `nullptr 1:1` will be
2529 serialized as an element with an `xsi:nil` attribute, thus effectively
2530 revealing the NULL property of its value.
2531 
2532 A non-pointer data member that is explicitly marked as optional with `0:1` will
2533 be set to its default value when no XML value is presented to the deserializer.
2534 A default value can be assigned to a data member that has a primitive type or
2535 is a (smart) pointer to primitive type.
2536 
2537 Consider for example:
2538 
2539 ```cpp
2540 class ns__record
2541 {
2542  public:
2543  std::shared_ptr<std::string> name; // optional (0:1)
2544  uint64_t SSN 0:1 = 999; // forced this to be optional with default 999
2545  ns__record *spouse 1:1; // forced this to be required (only married people)
2546 };
2547 ```
2548 
2549 This class maps to a complexType in the soapcpp2-generated schema:
2550 
2551 <div class="alt">
2552 ```xml
2553 <complexType name="record">
2554  <sequence>
2555  <element name="name" type="xsd:string" minOccurs="0" maxOccurs="1" nillable="true"/>
2556  <element name="SSN" type="xsd:unsignedLong" minOccurs="0" maxOccurs="1" default="999"/>
2557  <element name="spouse" type="ns:record" minOccurs="1" maxOccurs="1" nillable="true"/>
2558  </sequence>
2559 </complexType>
2560 ```
2561 </div>
2562 
2563 An example XML instance of `ns__record` with its `name` string value set to
2564 `Joe`, `SSN` set to its default, and `spouse` set to NULL:
2565 
2566 <div class="alt">
2567 ```xml
2568 <ns:record xmlns:ns="urn:types" ...>
2569  <name>Joe</name>
2570  <SSN>999</SSN>
2571  <spouse xsi:nil="true"/>
2572 </ns:record>
2573 ```
2574 </div>
2575 
2576 @note In general, a smart pointer is simply declared as a `volatile` template
2577 in a gSOAP header file for soapcpp2:
2578 
2579 ```cpp
2580 volatile template <class T> class NAMESPACE::shared_ptr;
2581 ```
2582 
2583 @note The soapcpp2 tool generates code that uses `NAMESPACE::shared_ptr` and
2584 `NAMESPACE::make_shared` to create shared pointers to objects, where
2585 `NAMESPACE` is any valid C++ namespace such as `std` and `boost` if you have
2586 Boost installed.
2587 
2588 🔝 [Back to table of contents](#)
2589 
2590 ### Container and array members and their occurrence constraints {#toxsd9-9}
2591 
2592 Class and struct data member types that are containers `std::deque`,
2593 `std::list`, `std::vector` and `std::set` are serialized as a collection of
2594 the values they contain. You can also serialize dynamic arrays, which is the
2595 alternative for C to store collections of data. Let's start with STL containers.
2596 
2597 You can use `std::deque`, `std::list`, `std::vector`, and `std::set` containers
2598 by importing:
2599 
2600 ```cpp
2601 #import "import/stl.h" // import all containers
2602 #import "import/stldeque.h" // import deque
2603 #import "import/stllist.h" // import list
2604 #import "import/stlvector.h" // import vector
2605 #import "import/stlset.h" // import set
2606 ```
2607 
2608 For example, to use a vector data mamber to store names in a record:
2609 
2610 ```cpp
2611 #import "import/stlvector.h"
2612 class ns__record
2613 {
2614  public:
2615  std::vector<std::string> names;
2616  uint64_t SSN;
2617 };
2618 ```
2619 
2620 To limit the number of names in the vector within reasonable bounds, occurrence
2621 constraints are associated with the container. Occurrence constraints are of
2622 the form `minOccurs : maxOccurs`:
2623 
2624 ```cpp
2625 #import "import/stlvector.h"
2626 class ns__record
2627 {
2628  public:
2629  std::vector<std::string> names 1:10;
2630  uint64_t SSN;
2631 };
2632 ```
2633 
2634 This class maps to a complexType in the soapcpp2-generated schema:
2635 
2636 <div class="alt">
2637 ```xml
2638 <complexType name="record">
2639  <sequence>
2640  <element name="name" type="xsd:string" minOccurs="1" maxOccurs="10"/>
2641  <element name="SSN" type="xsd:unsignedLong" minOccurs="1" maxOccurs="1""/>
2642  </sequence>
2643 </complexType>
2644 ```
2645 </div>
2646 
2647 @note In general, a container is simply declared as a template in a gSOAP
2648 header file for soapcpp2. All class templates are considered containers
2649 (except when declared `volatile`, see smart pointers). For example,
2650 `std::vector` is declared in `gsoap/import/stlvector.h` as:
2651 
2652 ```cpp
2653 template <class T> class std::vector;
2654 ```
2655 
2656 @note You can define and use your own containers. The soapcpp2 tool generates
2657 code that uses the following members of the `template <typename T> class C`
2658 container:
2659 
2660 ```cpp
2661 void C::clear()
2662 C::iterator C::begin()
2663 C::const_iterator C::begin() const
2664 C::iterator C::end()
2665 C::const_iterator C::end() const
2666 size_t C::size() const
2667 C::iterator C::insert(C::iterator pos, const T& val)
2668 ```
2669 
2670 @note For more details see the example `simple_vector` container with
2671 documentation in the package under `gsoap/samples/template`.
2672 
2673 Because C does not support a container template library, we can use a
2674 dynamically-sized array of values. This array is declared as a size-pointer
2675 pair of members within a struct or class. The array size information is stored
2676 in a special size tag member with the name `__size` or `__sizeX`, where `X` can
2677 be any name, or by an `$int` member to identify the member as a special size
2678 tag:
2679 
2680 ```cpp
2681 struct ns__record
2682 {
2683  $int sizeofnames; // array size
2684  char* *names; // array of char* names
2685  uint64_t SSN;
2686 };
2687 ```
2688 
2689 This class maps to a complexType in the soapcpp2-generated schema:
2690 
2691 <div class="alt">
2692 ```xml
2693 <complexType name="record">
2694  <sequence>
2695  <element name="name" type="xsd:string" minOccurs="0" maxOccurs="unbounded" nillable="true"/>
2696  <element name="SSN" type="xsd:unsignedLong" minOccurs="1" maxOccurs="1""/>
2697  </sequence>
2698 </complexType>
2699 ```
2700 </div>
2701 
2702 To limit the number of names in the array within reasonable bounds, occurrence
2703 constraints are associated with the array size member. Occurrence constraints
2704 are of the form `minOccurs : maxOccurs`:
2705 
2706 ```cpp
2707 struct ns__record
2708 {
2709  $int sizeofnames 1:10; // array size 1..10
2710  char* *names; // array of one to ten char* names
2711  uint64_t SSN;
2712 };
2713 ```
2714 
2715 This class maps to a complexType in the soapcpp2-generated schema:
2716 
2717 <div class="alt">
2718 ```xml
2719 <complexType name="record">
2720  <sequence>
2721  <element name="name" type="xsd:string" minOccurs="1" maxOccurs="10" nillable="true"/>
2722  <element name="SSN" type="xsd:unsignedLong" minOccurs="1" maxOccurs="1""/>
2723  </sequence>
2724 </complexType>
2725 ```
2726 </div>
2727 
2728 🔝 [Back to table of contents](#)
2729 
2730 ### Tagged union members {#toxsd9-10}
2731 
2732 A union member in a class or in a struct cannot be serialized unless a
2733 discriminating *variant selector* member is provided that tells the serializer
2734 which union field to serialize. This effectively creates a *tagged union*.
2735 
2736 The variant selector is associated with the union as a selector-union pair of members.
2737 The variant selector is a member with the name `__union` or `__unionX`, where
2738 `X` can be any name, or by an `$int` member to identify the member as a variant
2739 selector tag:
2740 
2741 ```cpp
2742 class ns__record
2743 {
2744  public:
2745  $int xORnORs; // variant selector with values SOAP_UNION_fieldname
2746  union choice
2747  {
2748  float x;
2749  int n;
2750  char *s;
2751  } u;
2752  std::string name;
2753 };
2754 ```
2755 
2756 The variant selector values are auto-generated based on the union name `choice`
2757 and the names of its members `x`, `n`, and `s`:
2758 
2759 - `xORnORs = SOAP_UNION_choice_x` when `u.x` is valid.
2760 - `xORnORs = SOAP_UNION_choice_n` when `u.n` is valid.
2761 - `xORnORs = SOAP_UNION_choice_s` when `u.s` is valid.
2762 - `xORnORs = 0` when none are valid (should only be used with great care,
2763  because XSD validation may fail when content is required but absent).
2764 
2765 This class maps to a complexType with a sequence and choice in the
2766 soapcpp2-generated schema:
2767 
2768 <div class="alt">
2769 ```xml
2770 <complexType name="record">
2771  <sequence>
2772  <choice>
2773  <element name="x" type="xsd:float" minOccurs="1" maxOccurs="1"/>
2774  <element name="n" type="xsd:int" minOccurs="1" maxOccurs="1"/>
2775  <element name="s" type="xsd:string" minOccurs="0" maxOccurs="1" nillable="true"/>
2776  </choice>
2777  <element name="names" type="xsd:string" minOccurs="1" maxOccurs="1" nillable="true"/>
2778  </sequence>
2779 </complexType>
2780 ```
2781 </div>
2782 
2783 An STL container or dynamic array of a union requires wrapping the variant
2784 selector and union member in a struct:
2785 
2786 ```cpp
2787 class ns__record
2788 {
2789  public:
2790  std::vector<
2791  struct ns__data // data with a choice of x, n, or s
2792  {
2793  $int xORnORs; // variant selector with values SOAP_UNION_fieldname
2794  union choice
2795  {
2796  float x;
2797  int n;
2798  char *s;
2799  } u;
2800  }> data; // vector with data
2801 };
2802 ```
2803 
2804 and an equivalent definition with a dynamic array instead of a `std::vector`
2805 (you can use this in C with structs):
2806 
2807 ```cpp
2808 class ns__record
2809 {
2810  public:
2811  $int sizeOfdata; // size of dynamic array
2812  struct ns__data // data with a choice of x, n, or s
2813  {
2814  $int xORnORs; // variant selector with values SOAP_UNION_fieldname
2815  union choice
2816  {
2817  float x;
2818  int n;
2819  char *s;
2820  } u;
2821  } *data; // points to the data array of length sizeOfdata
2822 };
2823 ```
2824 
2825 This maps to two complexTypes in the soapcpp2-generated schema:
2826 
2827 <div class="alt">
2828 ```xml
2829 <complexType name="data">
2830  <choice>
2831  <element name="x" type="xsd:float" minOccurs="1" maxOccurs="1"/>
2832  <element name="n" type="xsd:int" minOccurs="1" maxOccurs="1"/>
2833  <element name="s" type="xsd:string" minOccurs="0" maxOccurs="1" nillable="true"/>
2834  </choice>
2835 </complexType>
2836 <complexType name="record">
2837  <sequence>
2838  <element name="data" type="ns:data" minOccurs="0" maxOccurs="unbounded"/>
2839  </sequence>
2840 </complexType>
2841 ```
2842 </div>
2843 
2844 The XML value space consists of a sequence of item elements each wrapped in an
2845 data element:
2846 
2847 <div class="alt">
2848 ```xml
2849 <ns:record xmlns:ns="urn:types" ...>
2850  <data>
2851  <n>123</n>
2852  </data>
2853  <data>
2854  <x>3.1</x>
2855  </data>
2856  <data>
2857  <s>hello</s>
2858  </data>
2859  <data>
2860  <s>world</s>
2861  </data>
2862 </ns:record>
2863 ```
2864 </div>
2865 
2866 To remove the wrapping data element, simply rename the wrapping struct and
2867 member to `__data` to make this member invisible to the serializer with the
2868 double underscore prefix naming convention. Also use a dynamic array instead
2869 of a STL container (you can use this in C with structs):
2870 
2871 ```cpp
2872 class ns__record
2873 {
2874  public:
2875  $int sizeOfdata; // size of dynamic array
2876  struct __data // contains choice of x, n, or s
2877  {
2878  $int xORnORs; // variant selector with values SOAP_UNION_fieldname
2879  union choice
2880  {
2881  float x;
2882  int n;
2883  char *s;
2884  } u;
2885  } *__data; // points to the data array of length sizeOfdata
2886 };
2887 ```
2888 
2889 This maps to a complexType in the soapcpp2-generated schema:
2890 
2891 <div class="alt">
2892 ```xml
2893 <complexType name="record">
2894  <sequence minOccurs="0" maxOccurs="unbounded">
2895  <choice>
2896  <element name="x" type="xsd:float" minOccurs="1" maxOccurs="1"/>
2897  <element name="n" type="xsd:int" minOccurs="1" maxOccurs="1"/>
2898  <element name="s" type="xsd:string" minOccurs="0" maxOccurs="1" nillable="true"/>
2899  </choice>
2900  </sequence>
2901 </complexType>
2902 ```
2903 </div>
2904 
2905 The XML value space consists of a sequence of `<x>`, `<n>`, and/or `<s>`
2906 elements:
2907 
2908 <div class="alt">
2909 ```xml
2910 <ns:record xmlns:ns="urn:types" ...>
2911  <n>123</n>
2912  <x>3.1</x>
2913  <s>hello</s>
2914  <s>world</s>
2915 </ns:record>
2916 ```
2917 </div>
2918 
2919 Please note that structs, classes, and unions are unnested by soapcpp2 (as in
2920 the C standard of nested structs and unions). Therefore, the `choice` union in
2921 the `ns__record` class is redeclared at the top level despite its nesting
2922 within the `ns__record` class. This means that you will have to choose a
2923 unique name for each nested struct, class, and union.
2924 
2925 🔝 [Back to table of contents](#)
2926 
2927 ### Tagged void pointer members {#toxsd9-11}
2928 
2929 To serialize data pointed to by `void*` requires run-time type information that
2930 tells the serializer what type of data to serialize by means of a *tagged void
2931 pointer*. This type information is stored in a special type tag member of a
2932 struct/class with the name `__type` or `__typeX`, where `X` can be any name, or
2933 alternatively by an `$int` special member of any name as a type tag:
2934 
2935 ```cpp
2936 class ns__record
2937 {
2938  public:
2939  $int typeOfdata; // type tag with values SOAP_TYPE_T
2940  void *data; // points to some data of type T
2941 };
2942 ```
2943 
2944 A type tag member has nonzero values `SOAP_TYPE_T` where `T` is the name of a
2945 struct/class or the name of a primitive type, such as `int`, `std__string` (for
2946 `std::string`), `string` (for `char*`).
2947 
2948 This class maps to a complexType with a sequence in the soapcpp2-generated
2949 schema:
2950 
2951 <div class="alt">
2952 ```xml
2953 <complexType name="record">
2954  <sequence>
2955  <element name="data" type="xsd:anyType" minOccurs="0" maxOccurs="1"/>
2956  </sequence>
2957 </complexType>
2958 ```
2959 </div>
2960 
2961 The XML value space consists of the XML value space of the type with the
2962 addition of an `xsi:type` attribute to the enveloping element:
2963 
2964 <div class="alt">
2965 ```xml
2966 <ns:record xmlns:ns="urn:types" ...>
2967  <data xsi:type="xsd:int">123</data>
2968 </ns:record>
2969 ```
2970 </div>
2971 
2972 This `xsi:type` attribute is important for the receiving end to distinguish
2973 the type of data to instantiate. The receiver cannot deserialize the data
2974 without an `xsd:type` attribute.
2975 
2976 You can find the `SOAP_TYPE_T` name of each serializable type in the
2977 auto-generated soapStub.h file.
2978 
2979 Also all serializable C++ classes have a virtual `int T::soap_type()` member
2980 that returns their `SOAP_TYPE_T` value that you can use.
2981 
2982 When the `void*` pointer is NULL or when `typeOfdata` is zero, the data is not
2983 serialized.
2984 
2985 An STL container or dynamic array of `void*` pointers to `xsd:anyType` data
2986 requires wrapping the type tag and `void*` members in a struct:
2987 
2988 ```cpp
2989 class ns__record
2990 {
2991  public:
2992  std::vector<
2993  struct ns__data // data with an xsd:anyType item
2994  {
2995  $int typeOfitem; // type tag with values SOAP_TYPE_T
2996  void *item; // points to some item of type T
2997  }> data; // vector with data
2998 };
2999 ```
3000 
3001 and an equivalent definition with a dynamic array instead of a `std::vector`
3002 (you can use this in C with structs):
3003 
3004 ```cpp
3005 class ns__record
3006 {
3007  public:
3008  $int sizeOfdata; // size of dynamic array
3009  struct ns__data // data with an xsd:anyType item
3010  {
3011  $int typeOfitem; // type tag with values SOAP_TYPE_T
3012  void *item; // points to some item of type T
3013  } *data; // points to the data array of length sizeOfdata
3014 };
3015 ```
3016 
3017 This maps to two complexTypes in the soapcpp2-generated schema:
3018 
3019 <div class="alt">
3020 ```xml
3021 <complexType name="data">
3022  <sequence>
3023  <element name="item" type="xsd:anyType" minOccurs="1" maxOccurs="1" nillable="true"/>
3024  </sequence>
3025 </complexType>
3026 <complexType name="record">
3027  <sequence>
3028  <element name="data" type="ns:data" minOccurs="0" maxOccurs="unbounded"/>
3029  </sequence>
3030 </complexType>
3031 ```
3032 </div>
3033 
3034 The XML value space consists of a sequence of item elements each wrapped in a
3035 data element:
3036 
3037 <div class="alt">
3038 ```xml
3039 <ns:record xmlns:ns="urn:types" ...>
3040  <data>
3041  <item xsi:type="xsd:int">123</item>
3042  </data>
3043  <data>
3044  <item xsi:type="xsd:double">3.1</item>
3045  </data>
3046  <data>
3047  <item xsi:type="xsd:string">abc</item>
3048  </data>
3049 </ns:record>
3050 ```
3051 </div>
3052 
3053 To remove the wrapping data elements, simply rename the wrapping struct and
3054 member to `__data` to make this member invisible to the serializer with the
3055 double underscore prefix naming convention. Also use a dynamic array instead
3056 of a STL container (you can use this in C with structs):
3057 
3058 ```cpp
3059 class ns__record
3060 {
3061  public:
3062  $int sizeOfdata; // size of dynamic array
3063  struct __data // contains xsd:anyType item
3064  {
3065  $int typeOfitem; // type tag with values SOAP_TYPE_T
3066  void *item; // points to some item of type T
3067  } *__data; // points to the data array of length sizeOfdata
3068 };
3069 ```
3070 
3071 This maps to a complexType in the soapcpp2-generated schema:
3072 
3073 <div class="alt">
3074 ```xml
3075 <complexType name="record">
3076  <sequence minOccurs="0" maxOccurs="unbounded">
3077  <element name="item" type="xsd:anyType" minOccurs="1" maxOccurs="1"/>
3078  </sequence>
3079 </complexType>
3080 ```
3081 </div>
3082 
3083 The XML value space consists of a sequence of data elements:
3084 
3085 <div class="alt">
3086 ```xml
3087 <ns:record xmlns:ns="urn:types" ...>
3088  <item xsi:type="xsd:int">123</item>
3089  <item xsi:type="xsd:double">3.1</item>
3090  <item xsi:type="xsd:string">abc</item>
3091 </ns:record>
3092 ```
3093 </div>
3094 
3095 Again, please note that structs, classes, and unions are unnested by soapcpp2
3096 (as in the C standard of nested structs and unions). Therefore, the `__data`
3097 struct in the `ns__record` class is redeclared at the top level despite its
3098 nesting within the `ns__record` class. This means that you will have to choose
3099 a unique name for each nested struct, class, and union.
3100 
3101 @see Section [XSD type bindings](#typemap2).
3102 
3103 🔝 [Back to table of contents](#)
3104 
3105 ### Adding get and set methods {#toxsd9-12}
3106 
3107 A public `get` method may be added to a class or struct, which will be
3108 triggered by the deserializer. This method will be invoked right after the
3109 instance is populated by the deserializer. The `get` method can be used to
3110 update or verify deserialized content. It should return `SOAP_OK` or set
3111 `soap::error` to a nonzero error code and return it.
3112 
3113 A public `set` method may be added to a class or struct, which will be
3114 triggered by the serializer. The method will be invoked just before the
3115 instance is serialized. Likewise, the `set` method should return `SOAP_OK` or
3116 set set `soap::error` to a nonzero error code and return it.
3117 
3118 For example, adding a `set` and `get` method to a class declaration:
3119 
3120 ```cpp
3121 class ns__record
3122 {
3123  public:
3124  int set(struct soap*); // triggered before serialization
3125  int get(struct soap*); // triggered after deserialization
3126  ...
3127 };
3128 ```
3129 
3130 To add these and othe rmethods to classes and structs with wsdl2h and
3131 `typemap.dat`, please see [class/struct member additions](#typemap3).
3132 
3133 🔝 [Back to table of contents](#)
3134 
3135 ### Operations on classes and structs {#toxsd9-13}
3136 
3137 The following functions/macros are generated by soapcpp2 for each type `T`,
3138 which should make it easier to send, receive, and copy XML data in C and in
3139 C++:
3140 
3141 - `int soap_write_T(struct soap*, T*)` writes an instance of `T` to a file via
3142  file descriptor `int soap::sendfd)` or to a stream via `std::ostream
3143  *soap::os` (C++ only) or saves into a NUL-terminated string by setting
3144  `const char **soap::os` to a string pointer to be set (C only). Returns
3145  `SOAP_OK` on success or an error code, also stored in `soap->error`.
3146 
3147 - `int soap_read_T(struct soap*, T*)` reads an instance of `T` from a file via
3148  file descriptor `int soap::recvfd)` or from a stream via `std::istream
3149  *soap::is` (C++ only) or reads from a NUL-termianted string `const char
3150  *soap::is` (C only). Returns `SOAP_OK` on success or an error code, also
3151  stored in `soap->error`.
3152 
3153 - `void soap_default_T(struct soap*, T*)` sets an instance `T` to its default
3154  value, resetting members of a struct to their initial values (for classes we
3155  use method `T::soap_default`, see below).
3156 
3157 - `T * soap_dup_T(struct soap*, T *dst, const T *src)` (soapcpp2 option `-Ec`)
3158  deep copy `src` into `dst`, replicating all deep cycles and shared pointers
3159  when a managing soap context is provided as argument. When `dst` is NULL,
3160  allocates space for `dst`. Deep copy is a tree when argument is NULL, but the
3161  presence of deep cycles will lead to non-termination. Use flag
3162  `SOAP_XML_TREE` with managing context to copy into a tree without cycles and
3163  pointers to shared objects. Returns `dst` (or allocated space when `dst` is
3164  NULL).
3165 
3166 - `void soap_del_T(const T*)` (soapcpp2 option `-Ed`) deletes all
3167  heap-allocated members of this object by deep deletion ONLY IF this object
3168  and all of its (deep) members are not managed by a soap context AND the deep
3169  structure is a tree (no cycles and co-referenced objects by way of multiple
3170  (non-smart) pointers pointing to the same data). Can be safely used after
3171  `soap_dup(NULL)` to delete the deep copy. Does not delete the object itself.
3172 
3173 When in C++ mode, soapcpp2 tool adds several methods to classes in addition to
3174 adding a default constructor and destructor (when these were not explicitly
3175 declared).
3176 
3177 The public methods added to a class `T`:
3178 
3179 - `virtual int T::soap_type(void)` returns a unique type ID (`SOAP_TYPE_T`).
3180  This numeric ID can be used to distinguish base from derived instances.
3181 
3182 - `virtual void T::soap_default(struct soap*)` sets all data members to
3183  default values.
3184 
3185 - `virtual void T::soap_serialize(struct soap*) const` serializes object to
3186  prepare for SOAP 1.1/1.2 encoded output (or with `SOAP_XML_GRAPH`) by
3187  analyzing its (cyclic) structures.
3188 
3189 - `virtual int T::soap_put(struct soap*, const char *tag, const char *type) const`
3190  emits object in XML, compliant with SOAP 1.1 encoding style, return error
3191  code or `SOAP_OK`. Requires `soap_begin_send(soap)` and
3192  `soap_end_send(soap)`.
3193 
3194 - `virtual int T::soap_out(struct soap*, const char *tag, int id, const char *type) const`
3195  emits object in XML, with tag and optional id attribute and `xsi:type`,
3196  return error code or `SOAP_OK`. Requires `soap_begin_send(soap)` and
3197  `soap_end_send(soap)`.
3198 
3199 - `virtual void * T::soap_get(struct soap*, const char *tag, const char *type)`
3200  Get object from XML, compliant with SOAP 1.1 encoding style, return pointer
3201  to object or NULL on error. Requires `soap_begin_recv(soap)` and
3202  `soap_end_recv(soap)`.
3203 
3204 - `virtual void *soap_in(struct soap*, const char *tag, const char *type)`
3205  Get object from XML, with matching tag and type (NULL matches any tag and
3206  type), return pointer to object or NULL on error. Requires
3207  `soap_begin_recv(soap)` and `soap_end_recv(soap)`
3208 
3209 - `virtual T * T::soap_alloc(void) const` returns a new object of type `T`,
3210  default initialized and not managed by a soap context.
3211 
3212 - `virtual T * T::soap_dup(struct soap*) const` (soapcpp2 option `-Ec`) returns
3213  a duplicate of this object by deep copying, replicating all deep cycles and
3214  shared pointers when a managing soap context is provided as argument. Deep
3215  copy is a tree when argument is NULL, but the presence of deep cycles will
3216  lead to non-termination. Use flag `SOAP_XML_TREE` with the managing context
3217  to copy into a tree without cycles and pointers to shared objects.
3218 
3219 - `virtual void T::soap_del() const` (soapcpp2 option `-Ed`) deletes all
3220  heap-allocated members of this object by deep deletion ONLY IF this object
3221  and all of its (deep) members are not managed by a soap context AND the deep
3222  structure is a tree (no cycles and co-referenced objects by way of multiple
3223  (non-smart) pointers pointing to the same data). Can be safely used after
3224  `soap_dup(NULL)` to delete the deep copy. Does not delete the object itself.
3225 
3226 Also for C++, there are four variations of `soap_new_T` for
3227 class/struct/template type `T` that soapcpp2 auto-generates to create instances
3228 on a context-managed heap:
3229 
3230 - `T * soap_new_T(struct soap*)` returns a new instance of `T` with default data
3231  member initializations that are set with the soapcpp2 auto-generated `void
3232  T::soap_default(struct soap*)` method), but ONLY IF the soapcpp2
3233  auto-generated default constructor is used that invokes `soap_default()` and
3234  was not replaced by a user-defined default constructor.
3235 
3236 - `T * soap_new_T(struct soap*, int n)` returns an array of `n` new instances of
3237  `T`. Similar to the above, instances are initialized.
3238 
3239 - `T * soap_new_req_T(struct soap*, ...)` returns a new instance of `T` and sets
3240  the required data members to the values specified in `...`. The required data
3241  members are those with nonzero minOccurs, see the subsections on
3242  [(smart) pointer members and their occurrence constraints](#toxsd9-8) and
3243  [container and array members and their occurrence constraints](#toxsd9-9).
3244 
3245 - `T * soap_new_set_T(struct soap*, ...)` returns a new instance of `T` and sets
3246  the public/serializable data members to the values specified in `...`.
3247 
3248 The above functions can be invoked with a NULL `soap` context, but we will be
3249 responsible to use `delete T` to remove this instance from the unmanaged heap.
3250 
3251 🔝 [Back to table of contents](#)
3252 
3253 Special classes and structs {#toxsd10}
3254 ---------------------------
3255 
3256 ### SOAP encoded arrays {#toxsd10-1}
3257 
3258 A class or struct with the following layout is a one-dimensional SOAP encoded
3259 Array type:
3260 
3261 ```cpp
3262 class ArrayOfT
3263 {
3264  public:
3265  T *__ptr; // array pointer
3266  int __size; // array size
3267 };
3268 ```
3269 
3270 where `T` is the array element type. A multidimensional SOAP Array is:
3271 
3272 ```cpp
3273 class ArrayOfT
3274 {
3275  public:
3276  T *__ptr; // array pointer
3277  int __size[N]; // array size of each dimension
3278 };
3279 ```
3280 
3281 where `N` is the constant number of dimensions. The pointer points to an array
3282 of `__size[0]*__size[1]* ... * __size[N-1]` elements.
3283 
3284 This maps to a complexType restriction of SOAP-ENC:Array in the
3285 soapcpp2-generated schema:
3286 
3287 <div class="alt">
3288 ```xml
3289 <complexType name="ArrayOfT">
3290  <complexContent>
3291  <restriction base="SOAP-ENC:Array">
3292  <sequence>
3293  <element name="item" type="T" minOccurs="0" maxOccurs="unbounded" nillable="true"/>
3294  </sequence>
3295  <attribute ref="SOAP-ENC:arrayType" WSDL:arrayType="ArrayOfT[]"/>
3296  </restriction>
3297  </complexContent>
3298 </complexType>
3299 ```
3300 </div>
3301 
3302 The name of the class can be arbitrary. We often use `ArrayOfT` without a
3303 prefix to distinguish arrays from other classes and structs.
3304 
3305 With SOAP 1.1 encoding, an optional offset member can be added that controls
3306 the start of the index range for each dimension:
3307 
3308 ```cpp
3309 class ArrayOfT
3310 {
3311  public:
3312  T *__ptr; // array pointer
3313  int __size[N]; // array size of each dimension
3314  int __offset[N]; // array offsets to start each dimension
3315 };
3316 ```
3317 
3318 For example, we can define a matrix of floats as follows:
3319 
3320 ```cpp
3321 class Matrix
3322 {
3323  public:
3324  double *__ptr;
3325  int __size[2];
3326 };
3327 ```
3328 
3329 The following code populates the matrix and serializes it in XML:
3330 
3331 ```cpp
3332 soap *soap = soap_new1(SOAP_XML_INDENT);
3333 Matrix A;
3334 double a[6] = { 1, 2, 3, 4, 5, 6 };
3335 A.__ptr = a;
3336 A.__size[0] = 2;
3337 A.__size[1] = 3;
3338 soap_write_Matrix(soap, &A);
3339 ```
3340 
3341 Matrix A is serialized as an array with 2x3 values:
3342 
3343 <div class="alt">
3344 ```xml
3345 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:double[2,3]" ...>
3346  <item>1</item>
3347  <item>2</item>
3348  <item>3</item>
3349  <item>4</item>
3350  <item>5</item>
3351  <item>6</item>
3352 </SOAP-ENC:Array>
3353 ```
3354 </div>
3355 
3356 🔝 [Back to table of contents](#)
3357 
3358 ### XSD hexBinary and base64Binary types {#toxsd10-2}
3359 
3360 A special case of a one-dimensional array is used to define `xsd:hexBinary` and
3361 `xsd:base64Binary` types when the pointer type is `unsigned char`:
3362 
3363 ```cpp
3364 class xsd__hexBinary
3365 {
3366  public:
3367  unsigned char *__ptr; // points to raw binary data
3368  int __size; // size of data
3369 };
3370 ```
3371 
3372 and
3373 
3374 ```cpp
3375 class xsd__base64Binary
3376 {
3377  public:
3378  unsigned char *__ptr; // points to raw binary data
3379  int __size; // size of data
3380 };
3381 ```
3382 
3383 🔝 [Back to table of contents](#)
3384 
3385 ### MIME/MTOM attachment binary types {#toxsd10-3}
3386 
3387 A class or struct with a binary content layout can be extended to support
3388 MIME/MTOM (and older DIME) attachments, such as in xop:Include elements:
3389 
3390 ```cpp
3391 //gsoap xop schema import: http://www.w3.org/2004/08/xop/include
3392 class _xop__Include
3393 {
3394  public:
3395  unsigned char *__ptr; // points to raw binary data
3396  int __size; // size of data
3397  char *id; // NULL to generate an id, or set to a unique UUID
3398  char *type; // MIME type of the data
3399  char *options; // optional description of MIME attachment
3400 };
3401 ```
3402 
3403 Attachments are beyond the scope of this document. The `SOAP_ENC_MIME` and
3404 `SOAP_ENC_MTOM` context flag must be set to enable attachments. See the
3405 [gSOAP user guide](http://www.genivia.com/doc/soapdoc2.html) for more details.
3406 
3407 🔝 [Back to table of contents](#)
3408 
3409 ### Wrapper class/struct with simpleContent {#toxsd10-4}
3410 
3411 A class or struct with the following layout is a complexType that wraps
3412 simpleContent:
3413 
3414 ```cpp
3415 class ns__simple
3416 {
3417  public:
3418  T __item;
3419 };
3420 ```
3421 
3422 The type `T` is a primitive type (`bool`, `enum`, `time_t`, numeric and string
3423 types), `xsd__hexBinary`, `xsd__base64Binary`, and custom serializers, such as
3424 `xsd__dateTime`.
3425 
3426 This maps to a complexType with simpleContent in the soapcpp2-generated schema:
3427 
3428 <div class="alt">
3429 ```xml
3430 <complexType name="simple">
3431  <simpleContent>
3432  <extension base="T"/>
3433  </simpleContent>
3434 </complexType>
3435 ```
3436 </div>
3437 
3438 A wrapper class/struct may include any number of attributes declared with `@`.
3439 
3440 🔝 [Back to table of contents](#)
3441 
3442 ### DOM anyType and anyAttribute {#toxsd10-5}
3443 
3444 Use of a DOM is optional and enabled by `#import "dom.h"` to use the DOM
3445 `xsd__anyType` element node and `xsd__anyAttribute` attribute node:
3446 
3447 ```cpp
3448 #import "dom.h"
3449 
3450 class ns__record
3451 {
3452  public:
3453  @xsd__anyAttribute attributes; // list of DOM attributes
3454  ...
3455  xsd__anyType *name; // optional DOM element
3456 };
3457 ```
3458 
3459 where `name` contains XML stored in a DOM node set and `attributes` is a list
3460 of all visibly rendered attributes. The name `attributes` is arbitrary and any
3461 name will suffice.
3462 
3463 You should place the `xsd__anyType` members at the end of the struct or class.
3464 This ensures that the DOM members are populated last as a "catch all". A
3465 member name starting with double underscore is a wildcard member name and
3466 matches any XML tag. These members are placed at the end of a struct or class
3467 automatically by soapcpp2.
3468 
3469 An `#import "dom.h"` import is automatically added by wsdl2h with option `-d`
3470 to bind `xsd:anyType` to DOM nodes, and also to populate `xsd:any`,
3471 `xsd:anyAttribute` and `xsd:mixed` XML content:
3472 
3473 ```cpp
3474 #import "dom.h"
3475 
3476 class ns__record
3477 {
3478  public:
3479  ...
3480  @xsd__anyAttribute __anyAttribute; // optional DOM attributes
3481  std::vector<xsd__anyType> __any 0; // optional DOM elements
3482  xsd__anyType __mixed 0; // optional mixed content
3483 };
3484 ```
3485 
3486 where the members prefixed with `__` are "invisible" to the XML parser, meaning
3487 that these members are not bound to XML tag names.
3488 
3489 In C you can use a dynamic arrary instead of `std::vector`:
3490 
3491 ```cpp
3492 #import "dom.h"
3493 
3494 struct ns__record
3495 {
3496  ...
3497  @xsd__anyAttribute __anyAttribute; // optional DOM attributes
3498  $int __sizeOfany; // size of the array
3499  xsd__anyType *__any; // optional DOM elements
3500  xsd__anyType __mixed 0; // optional mixed content
3501 };
3502 ```
3503 
3504 Classes can inherit DOM, which enables full use of polymorphism with one base
3505 DOM class:
3506 
3507 ```cpp
3508 #import "dom.h"
3509 
3510 class ns__record : public xsd__anyType
3511 {
3512  ...
3513  std::vector<xsd__anyType*> array; // array of objects of any class
3514 };
3515 ```
3516 
3517 This permits an `xsd__anyType` pointer to refer to a derived class such as
3518 `ns__record`, which will be serialized with an `xsi:type` attribute that is
3519 set to "ns:record". The `xsi:type` attributes add the necessary type information
3520 to distinguish the XML content from the DOM base type. This is important for
3521 the receiving end: without `xsd:type` attributes with type names, only base DOM
3522 objects are recognized and instantiated.
3523 
3524 Because C lacks OOP principles such as class inheritance and polymorphism, you
3525 will need to use the special [`void*` members](#toxsd9-11) to serialize data
3526 pointed to by a `void*` member.
3527 
3528 To ensure that wsdl2h generates pointer-based `xsd__anyType` DOM nodes with
3529 option `-d` for `xsd:any`, add the following line to `typemap.dat`:
3530 
3531  xsd__any = | xsd__anyType*
3532 
3533 This lets wsdl2h produce class/struct members and containers with
3534 `xsd__anyType*` for `xsd:any` instead of `xsd__anyType`. To just force all
3535 `xsd:anyType` uses to be pointer-based, declare in `typemap.dat`:
3536 
3537  xsd__anyType = | xsd__anyType*
3538 
3539 If you use wsdl2h with option `-p` with option `-d` then every class will
3540 inherit DOM as shown above. Without option `-d`, an `xsd__anyType` type is
3541 generated to serve as the root type in the type hierarchy:
3542 
3543 ```cpp
3544 class xsd__anyType { _XML __item; struct soap *soap; };
3545 
3546 class ns__record : public xsd__anyType
3547 {
3548  ...
3549 };
3550 ```
3551 
3552 where the `_XML __item` member holds any XML content as a literal XML string.
3553 
3554 To use the DOM API, compile `dom.c` (or `dom.cpp` for C++), or link with
3555 `-lgsoapssl` (or `-lgsoapssl++` for C++).
3556 
3557 @see Documentation of [XML DOM and XPath](http://www.genivia.com/doc/dom/html)
3558 for more details.
3559 
3560 🔝 [Back to table of contents](#)
3561 
3562 Directives {#directives}
3563 ==========
3564 
3565 You can use `//gsoap` directives in the gSOAP header file with the data binding
3566 interface for soapcpp2. These directives are used to configure the code
3567 generated by soapcpp2 by declaring various. properties of Web services and XML
3568 schemas. When using the wsdl2h tool, you will notice that wsdl2h generates
3569 directives automatically based on the WSDL and XSD input.
3570 
3571 Service directives are applicable to service and operations described by WSDL.
3572 Schema directives are applicable to types, elements, and attributes defined by
3573 XML schemas.
3574 
3575 🔝 [Back to table of contents](#)
3576 
3577 Service directives {#directives-1}
3578 ------------------
3579 
3580 A service directive must start at a new line and is of the form:
3581 
3582 ```cpp
3583 //gsoap <prefix> service <property>: <value>
3584 ```
3585 
3586 where `<prefix>` is the XML namespace prefix of a service binding. The
3587 `<property>` and `<value>` fields are one of the following:
3588 
3589 property | value
3590 --------------- | -----
3591 `name` | name of the service, optionally followed by text describing the service
3592 `namespace` | URI of the WSDL targetNamespace
3593 `documentation` | text describing the service (see also the `name` property), multiple permitted
3594 `doc` | same as above, shorthand form
3595 `style` | `document` (default) SOAP messaging style or `rpc` for SOAP RPC
3596 `encoding` | `literal` (default), `encoded` for SOAP encoding, or a custom URI
3597 `protocol` | specifies SOAP or REST, see below
3598 `port` | URL of the service endpoint, usually an http or https address
3599 `transport` | URI declaration of the transport, usually `http://schemas.xmlsoap.org/soap/http`
3600 `definitions` | name of the WSDL definitions/\@name
3601 `type` | name of the WSDL definitions/portType/\@name (WSDL2.0 interface/\@name)
3602 `binding` | name of the WSDL definitions/binding/\@name
3603 `portName` | name of the WSDL definitions/service/port/\@name
3604 `portType` | an alias for the `type` property
3605 `interface` | an alias for the `type` property
3606 `location` | an alias for the `port` property
3607 `endpoint` | an alias for the `port` property
3608 
3609 The service `name` and `namespace` properties are required in order to generate
3610 a valid WSDL with soapcpp2. The other properties are optional.
3611 
3612 The `style` and `encoding` property defaults are changed with soapcpp2 option
3613 `-e` to `rpc` and `encoded`, respectively.
3614 
3615 The `protocol` property is `SOAP` by default (SOAP 1.1). Protocol property
3616 values are:
3617 
3618 protocol value | description
3619 -------------- | -----------
3620 `SOAP` | SOAP transport, supporting both SOAP 1.1 and 1.2
3621 `SOAP1.1` | SOAP 1.1 transport (same as soapcpp2 option `-1`)
3622 `SOAP1.2` | SOAP 1.2 transport (same as soapcpp2 option `-2`)
3623 `SOAP-GET` | one-way SOAP 1.1 or 1.2 with HTTP GET
3624 `SOAP1.1-GET` | one-way SOAP 1.1 with HTTP GET
3625 `SOAP1.2-GET` | one-way SOAP 1.2 with HTTP GET
3626 `HTTP` | non-SOAP REST protocol with HTTP POST
3627 `POST` | non-SOAP REST protocol with HTTP POST
3628 `GET` | non-SOAP REST protocol with HTTP GET
3629 `PUT` | non-SOAP REST protocol with HTTP PUT
3630 `DELETE` | non-SOAP REST protocol with HTTP DELETE
3631 
3632 You can bind service operations to the WSDL namespace of a service by using the
3633 namespace prefix as part of the identifier name of the function that defines
3634 the service operation:
3635 
3636 ```cpp
3637 int prefix__func(arg1, arg2, ..., argn, result);
3638 ```
3639 
3640 You can override the `port` endpoint URL at runtime in the auto-generated
3641 `soap_call_prefix__func` service call (C/C++ client side) and in the C++ proxy
3642 class service call.
3643 
3644 🔝 [Back to table of contents](#)
3645 
3646 Service method directives {#directives-2}
3647 -------------------------
3648 
3649 Service properties are applicable to a service and to all of its operations.
3650 Service method directives are specifically applicable to a service operation.
3651 
3652 A service method directive is of the form:
3653 
3654 ```cpp
3655 //gsoap <prefix> service method-<property>: <method> <value>
3656 ```
3657 
3658 where `<prefix>` is the XML namespace prefix of a service binding and
3659 `<method>` is the unqualified name of a service operation. The `<property>`
3660 and `<value>` fields are one of the following:
3661 
3662 method property | value
3663 --------------------------- | -----
3664 `method-documentation` | text describing the service operation
3665 `method` | same as above, shorthand form
3666 `method-action` | `""` or URI SOAPAction HTTP header, or URL query string for REST protocols
3667 `method-input-action` | `""` or URI SOAPAction HTTP header of service request messages
3668 `method-output-action` | `""` or URI SOAPAction HTTP header of service response messages
3669 `method-fault-action` | `""` or URI SOAPAction HTTP header of service fault messages
3670 `method-header-part` | member name of the `SOAP_ENV__Header` struct used in SOAP Header
3671 `method-input-header-part` | member name of the `SOAP_ENV__Header` struct used in SOAP Headers of requests
3672 `method-output-header-part` | member name of the `SOAP_ENV__Header` struct used in SOAP Headers of responses
3673 `method-fault` | type name of a struct or class member used in `SOAP_ENV__Details` struct
3674 `method-mime-type` | REST content type or SOAP MIME attachment content type(s)
3675 `method-input-mime-type` | REST content type or SOAP MIME attachment content type(s) of request message
3676 `method-output-mime-type` | REST content type or SOAP MIME attachment content type(s) of response message
3677 `method-style` | `document` or `rpc`
3678 `method-encoding` | `literal`, `encoded`, or a custom URI for encodingStyle of messages
3679 `method-response-encoding` | `literal`, `encoded`, or a custom URI for encodingStyle of response messages
3680 `method-protocol` | SOAP or REST, see [service directives](#directives-1)
3681 
3682 The `method-header-part` properties can be repeated for a service operation to
3683 declare multiple SOAP Header parts that the service operation requires. You
3684 can use `method-input-header-part` and `method-output-header-part` to
3685 differentiate between request and response messages.
3686 
3687 The `method-fault` property can be repeated for a service operation to declare
3688 multiple faults that the service operation may return.
3689 
3690 The `method-action` property serves two purposes:
3691 
3692 -# To set the SOAPAction header for SOAP protocols, i.e. sets the
3693  definitions/binding/operation/SOAP:operation/\@soapAction.
3694 
3695 -# To set the URL query string for endpoints with REST protocols, i.e. sets the
3696  definitions/binding/operation/HTTP:operation/\@location, which specifies
3697  a URL query string (starts with a `?`) to complete the service endpoint URL
3698  or extends the endpoint URL with a local path (starts with a `/`).
3699 
3700 Use `method-input-action` and `method-output-action` to differentiate the
3701 SOAPAction between SOAP request and response messages.
3702 
3703 You can always override the port endpoint URL and action values at runtime in
3704 the auto-generated `soap_call_prefix__func` service call (C/C++ client side)
3705 and in the auto-generated C++ proxy class service calls. A runtime NULL
3706 endpoint URL and/or action uses the defaults set by these directives.
3707 
3708 The `method-mime-type` property serves two purposes:
3709 
3710 -# To set the type of MIME/MTOM attachments used with SOAP protocols. Multiple
3711  attachment types can be declared for a SOAP service operation, i.e. adds
3712  definitions/binding/operation/input/MIME:multipartRelated/MIME:part/MIME:content/\@type
3713  for each type specified.
3714 
3715 -# To set the MIME type of a REST operation. This replaces XML declared in
3716  WSDL by definitions/binding/operation/(input|output)/MIME:mimeXml with
3717  MIME:content/\@type. Use `application/x-www-form-urlencoded` with REST POST
3718  and PUT protocols to send encoded form data automatically instead of XML.
3719  Only primitive type values can be transmitted with form data, such as
3720  numbers and strings, i.e. only types that are legal to use as
3721  [attributes members](#toxsd9-5).
3722 
3723 Use `method-input-mime-type` and `method-output-mime-type` to differentiate the
3724 attachment types between SOAP request and response messages.
3725 
3726 🔝 [Back to table of contents](#)
3727 
3728 Schema directives {#directives-3}
3729 -----------------
3730 
3731 A schema directive is of the form:
3732 
3733 ```cpp
3734 //gsoap <prefix> schema <property>: <value>
3735 ```
3736 
3737 where `<prefix>` is the XML namespace prefix of a schema. The `<property>` and
3738 `<value>` fields are one of the following:
3739 
3740 property | value
3741 --------------- | -----
3742 `namespace` | URI of the XSD targetNamespace
3743 `namespace2` | alternate URI for the XSD namespace (i.e. URI is also accepted by the XML parser)
3744 `import` | URI of imported namespace
3745 `form` | `unqualified` (default) or `qualified` local element and attribute form defaults
3746 `elementForm` | `unqualified` (default) or `qualified` local element form default
3747 `attributeForm` | `unqualified` (default) or `qualified` local attribute form default
3748 `typed` | `no` (default) or `yes` for serializers to add `xsi:type` attributes to XML
3749 
3750 To learn more about the local form defaults, see [qualified and unqualified members.](#toxsd9-6)
3751 
3752 The `typed` property is implicitly `yes` when soapcpp2 option `-t` is used.
3753 
3754 🔝 [Back to table of contents](#)
3755 
3756 Schema type directives {#directives-4}
3757 ----------------------
3758 
3759 A schema type directive is of the form:
3760 
3761 ```cpp
3762 //gsoap <prefix> schema type-<property>: <name> <value>
3763 //gsoap <prefix> schema type-<property>: <name>::<member> <value>
3764 ```
3765 
3766 where `<prefix>` is the XML namespace prefix of a schema and `<name>` is an
3767 unqualified name of a C/C++ type, and the optional `<member>` is a class/struct
3768 members or enum constant.
3769 
3770 You can describe a type:
3771 
3772 type property | value
3773 -------------------- | -----
3774 `type-documentation` | text describing the schema type
3775 `type` | same as above, shorthand form
3776 
3777 For example, you can add a description to an enumeration:
3778 
3779 ```cpp
3780 //gsoap ns schema type: Vowels The letters A, E, I, O, U, and sometimes Y
3781 //gsoap ns schema type: Vowels::Y A vowel, sometimes
3782 enum class ns__Vowels : char { A = 'A', E = 'E', I = 'I', O = 'O', U = 'U', Y = 'Y' };
3783 ```
3784 
3785 This documented enumeration maps to a simpleType restriction of `xsd:string` in
3786 the soapcpp2-generated schema:
3787 
3788 <div class="alt">
3789 ```xml
3790 <simpleType name="Vowels">
3791  <annotation>
3792  <documentation>The letters A, E, I, O, U, and sometimes Y</documentation>
3793  </annotation>
3794  <restriction base="xsd:string">
3795  <enumeration value="A"/>
3796  <enumeration value="E"/>
3797  <enumeration value="I"/>
3798  <enumeration value="O"/>
3799  <enumeration value="U"/>
3800  <enumeration value="Y">
3801  <annotation>
3802  <documentation>A vowel, sometimes</documentation>
3803  </annotation>
3804  <enumeration/>
3805  </restriction>
3806 </simpleType>
3807 ```
3808 </div>
3809 
3810 🔝 [Back to table of contents](#)
3811 
3812 Serialization rules {#rules}
3813 ===================
3814 
3815 A presentation on XML data bindings is not complete without discussing the
3816 serialization rules and options that put your data in XML on the wire or store
3817 it a file or buffer.
3818 
3819 There are several options to choose from to serialize data in XML. The choice
3820 depends on the use of the SOAP protocol or if SOAP is not required. The wsdl2h
3821 tool automates this for you by taking the WSDL transport bindings into account
3822 when generating the service functions in C and C++ that use SOAP or REST.
3823 
3824 The gSOAP tools are not limited to SOAP. The tools implement generic XML data
3825 bindings for SOAP, REST, and other uses of XML. So you can read and write XML
3826 using the serializing [operations on classes and structs](#toxsd9-13).
3827 
3828 The following sections briefly explain the serialization rules with respect to
3829 the SOAP protocol for XML Web services. A basic understanding of the SOAP
3830 protocol is useful when developing client and server applications that must
3831 interoperate with other SOAP applications.
3832 
3833 SOAP/REST Web service client and service operations are represented as
3834 functions in your gSOAP header file with the data binding interface for
3835 soapcpp2. The soapcpp2 tool will translate these function to client-side
3836 service invocation calls and server-side service operation dispatchers.
3837 
3838 A discussion of SOAP clients and servers is beyond the scope of this document.
3839 However, the SOAP options discussed here also apply to SOAP client and server
3840 development.
3841 
3842 🔝 [Back to table of contents](#)
3843 
3844 SOAP document versus rpc style {#doc-rpc}
3845 ------------------------------
3846 
3847 The `wsdl:binding/soap:binding/@style` attribute in the wsdl:binding section of
3848 a WSDL is either "document" or "rpc". The "rpc" style refers to SOAP RPC
3849 (Remote Procedure Call), which is more restrictive than the "document" style by
3850 requiring one XML element in the SOAP Body to act as the procedure name with
3851 XML subelements as its parameters.
3852 
3853 For example, the following directives in the gSOAP header file for soapcpp2
3854 declare that `DBupdate` is a SOAP RPC encoding service method:
3855 
3856 ```cpp
3857 //gsoap ns service namespace: urn:DB
3858 //gsoap ns service method-protocol: DBupdate SOAP
3859 //gsoap ns service method-style: DBupdate rpc
3860 int ns__DBupdate(...);
3861 ```
3862 
3863 The XML payload has a SOAP envelope, optional SOAP header, and a SOAP body with
3864 one element representing the operation with the parameters as subelements:
3865 
3866 <div class="alt">
3867 ```xml
3868 <SOAP-ENV:Envelope
3869  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
3870  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
3871  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3872  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
3873  xmlsn:ns="urn:DB">
3874  <SOAP-ENV:Body>
3875  <ns:DBupdate>
3876  ...
3877  </ns:DBupdate>
3878  </SOAP-ENV:Body>
3879 </SOAP-ENV:Envelope>
3880 ```
3881 </div>
3882 
3883 The "document" style puts no restrictions on the SOAP Body content. However, we
3884 recommend that the first element's tag name in the SOAP Body should be unique
3885 to each type of operation, so that the receiver can dispatch the operation
3886 based on this element's tag name. Alternatively, the HTTP URL path can be used
3887 to specify the operation, or the HTTP action header can be used to dispatch
3888 operations automatically on the server side (soapcpp2 options -a and -A).
3889 
3890 🔝 [Back to table of contents](#)
3891 
3892 SOAP literal versus encoding {#lit-enc}
3893 ----------------------------
3894 
3895 The `wsdl:operation/soap:body/@use` attribute in the wsdl:binding section of a
3896 WSDL is either "literal" or "encoded". The "encoded" use refers to the SOAP
3897 encoding rules that support id-ref multi-referenced elements to serialize
3898 data as graphs.
3899 
3900 SOAP encoding is very useful if the data internally forms a graph (including
3901 cycles) and we want the graph to be serialized in XML in a format that ensures
3902 that its structure is preserved. In that case, SOAP 1.2 encoding is the best
3903 option.
3904 
3905 SOAP encoding also adds encoding rules for [SOAP arrays](#toxsd10) to serialize
3906 multi-dimensional arrays. The use of XML attributes to exchange XML data in
3907 SOAP encoding is not permitted. The only attributes permitted are the standard
3908 XSD attributes, SOAP encoding attributes (such as for arrays), and id-ref.
3909 
3910 For example, the following directives in the gSOAP header file for soapcpp2
3911 declare that `DBupdate` is a SOAP RPC encoding service method:
3912 
3913 ```cpp
3914 //gsoap ns service namespace: urn:DB
3915 //gsoap ns service method-protocol: DBupdate SOAP
3916 //gsoap ns service method-style: DBupdate rpc
3917 //gsoap ns service method-encoding: DBupdate encoded
3918 int ns__DBupdate(...);
3919 ```
3920 
3921 The XML payload has a SOAP envelope, optional SOAP header, and a SOAP body with
3922 an encodingStyle attribute for SOAP 1.1 encoding and an element representing the
3923 operation with parameters that are SOAP 1.1 encoded:
3924 
3925 <div class="alt">
3926 ```xml
3927 <SOAP-ENV:Envelope
3928  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
3929  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
3930  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3931  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
3932  xmlsn:ns="urn:DB">
3933  <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
3934  <ns:DBupdate>
3935  <records SOAP-ENC:arrayType="ns:record[3]">
3936  <item>
3937  <name href="#_1"/>
3938  <SSN>1234567890</SSN>
3939  </item>
3940  <item>
3941  <name>Jane</name>
3942  <SSN>1987654320</SSN>
3943  </item>
3944  <item>
3945  <name href="#_1"/>
3946  <SSN>2345678901</SSN>
3947  </item>
3948  </records>
3949  </ns:DBupdate>
3950  <id id="_1" xsi:type="xsd:string">Joe</id>
3951  </SOAP-ENV:Body>
3952 </SOAP-ENV:Envelope>
3953 ```
3954 </div>
3955 
3956 Note that the name "Joe" is shared by two records and the string is referenced
3957 by SOAP 1.1 href and id attributes.
3958 
3959 While gSOAP only introduces multi-referenced elements in the payload when they
3960 are actually multi-referenced in the data graph, other SOAP applications may
3961 render multi-referenced elements more aggressively. The example could also be
3962 rendered as:
3963 
3964 <div class="alt">
3965 ```xml
3966 <SOAP-ENV:Envelope
3967  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
3968  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
3969  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3970  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
3971  xmlsn:ns="urn:DB">
3972  <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
3973  <ns:DBupdate>
3974  <records SOAP-ENC:arrayType="ns:record[3]">
3975  <item href="#id1"/>
3976  <item href="#id2"/>
3977  <item href="#id3"/>
3978  </records>
3979  </ns:DBupdate>
3980  <id id="id1" xsi:type="ns:record">
3981  <name href="#id4"/>
3982  <SSN>1234567890</SSN>
3983  </id>
3984  <id id="id2" xsi:type="ns:record">
3985  <name href="#id5"/>
3986  <SSN>1987654320</SSN>
3987  </id>
3988  <id id="id3" xsi:type="ns:record">
3989  <name href="#id4"/>
3990  <SSN>2345678901</SSN>
3991  </id>
3992  <id id="id4" xsi:type="xsd:string">Joe</id>
3993  <id id="id5" xsi:type="xsd:string">Jane</id>
3994  </SOAP-ENV:Body>
3995 </SOAP-ENV:Envelope>
3996 ```
3997 </div>
3998 
3999 SOAP 1.2 encoding is cleaner and produces more accurate XML encodings of data
4000 graphs by setting the id attribute on the element that is referenced:
4001 
4002 <div class="alt">
4003 ```xml
4004 <SOAP-ENV:Envelope
4005  xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
4006  xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding"
4007  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4008  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
4009  xmlsn:ns="urn:DB">
4010  <SOAP-ENV:Body>
4011  <ns:DBupdate SOAP-ENV:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
4012  <records SOAP-ENC:itemType="ns:record" SOAP-ENC:arraySize="3">
4013  <item>
4014  <name SOAP-ENC:id="_1">Joe</name>
4015  <SSN>1234567890</SSN>
4016  </item>
4017  <item>
4018  <name>Jane</name>
4019  <SSN>1987654320</SSN>
4020  </item>
4021  <item>
4022  <name SOAP-ENC:ref="_1"/>
4023  <SSN>2345678901</SSN>
4024  </item>
4025  </records>
4026  </ns:DBupdate>
4027  </SOAP-ENV:Body>
4028 </SOAP-ENV:Envelope>
4029 ```
4030 </div>
4031 
4032 @note Some SOAP 1.2 applications consider the namespace `SOAP-ENC` of
4033 `SOAP-ENC:id` and `SOAP-ENC:ref` optional. The gSOAP SOAP 1.2 encoding
4034 serialization follows the 2007 standard, while accepting unqualified id and
4035 ref attributes.
4036 
4037 To remove all rendered id-ref multi-referenced elements in gSOAP, use the
4038 `SOAP_XML_TREE` flag to initialize the gSOAP engine context.
4039 
4040 Some XSD validation rules are turned off with SOAP encoding, because of the
4041 presence of additional attributes, such as id and ref/href, SOAP arrays with
4042 arbitrary element tags for array elements, and the occurrence of additional
4043 multi-ref elements in the SOAP 1.1 Body.
4044 
4045 The use of "literal" puts no restrictions on the XML in the SOAP Body. Full
4046 XSD validation is possible, which can be enabled with the `SOAP_XML_STRICT`
4047 flag to initialize the gSOAP engine context. However, data graphs will be
4048 serialized as trees and cycles in the data will be cut from the XML rendition.
4049 
4050 🔝 [Back to table of contents](#)
4051 
4052 SOAP 1.1 versus SOAP 1.2 {#soap}
4053 ------------------------
4054 
4055 There are two SOAP protocol versions: 1.1 and 1.2. The gSOAP tools can switch
4056 between the two versions seamlessly. You can declare the default SOAP version
4057 for a service operation as follows:
4058 
4059 ```cpp
4060 //gsoap ns service method-protocol: DBupdate SOAP1.2
4061 ```
4062 
4063 The gSOAP soapcpp2 auto-generates client and server code. At the client side,
4064 this operation sends data with SOAP 1.2 but accepts responses also in SOAP 1.1.
4065 At the server side, this operation accepts requests in SOAP 1.1 and 1.2 and
4066 will return responses in the same SOAP version.
4067 
4068 As we discussed in the previous section, the SOAP 1.2 protocol has a cleaner
4069 multi-referenced element serialization format that greatly enhances the
4070 accuracy of data graph serialization with SOAP RPC encoding and is therefore
4071 recommended.
4072 
4073 The SOAP 1.2 protocol default can also be set by importing and loading
4074 `gsoap/import/soap12.h`:
4075 
4076 ```cpp
4077 #import "soap12.h"
4078 ```
4079 
4080 🔝 [Back to table of contents](#)
4081 
4082 Non-SOAP XML serialization {#non-soap}
4083 --------------------------
4084 
4085 You can serialize data that is stored on the heap, on the stack (locals), and
4086 static data as long as the serializable (i.e. non-transient) members are
4087 properly initialized and pointers in the structures are either NULL or point to
4088 valid structures. Deserialized data is put on the heap and managed by the
4089 gSOAP engine context `struct soap`, see also [memory management](#memory).
4090 
4091 You can read and write XML directly to a file or stream with the serializing
4092 [operations on classes and structs](#toxsd9-13).
4093 
4094 To define and use XML Web service client and service operations, we can declare
4095 these operations in your gSOAP header file with the data binding interface for
4096 soapcpp2 as functions. The function are translated by soapcpp2 to client-side
4097 service invocation calls and server-side service operation dispatchers.
4098 
4099 The REST operations POST, GET, and PUT are declared with `//gsoap` directives
4100 in the gSOAP header file for soapcpp2. For example, a REST POST operation is
4101 declared as follows:
4102 
4103 ```cpp
4104 //gsoap ns service namespace: urn:DB
4105 //gsoap ns service method-protocol: DBupdate POST
4106 int ns__DBupdate(...);
4107 ```
4108 
4109 There is no SOAP Envelope and no SOAP Body in the payload for `DBupdate`. Also
4110 the XML serialization rules are identical to SOAP document/literal. The XML
4111 payload only has the operation name as an element with its parameters
4112 serialized as subelements:
4113 
4114 <div class="alt">
4115 ```xml
4116 <ns:DBupdate xmln:ns="urn:DB" ...>
4117  ...
4118 </ns:DBupdate>
4119 ```
4120 </div>
4121 
4122 To force id-ref serialization with REST similar to SOAP 1.2 multi-reference
4123 encoding, use the `SOAP_XML_GRAPH` flag to initialize the gSOAP engine context.
4124 The XML serialization includes id and ref attributes for multi-referenced
4125 elements as follows:
4126 
4127 <div class="alt">
4128 ```xml
4129 <ns:DBupdate xmln:ns="urn:DB" ...>
4130  <records>
4131  <item>
4132  <name id="_1">Joe</name>
4133  <SSN>1234567890</SSN>
4134  </item>
4135  <item>
4136  <name>Jane</name>
4137  <SSN>1987654320</SSN>
4138  </item>
4139  <item>
4140  <name ref="_1"/>
4141  <SSN>2345678901</SSN>
4142  </item>
4143  </records>
4144 </ns:DBupdate>
4145 ```
4146 </div>
4147 
4148 🔝 [Back to table of contents](#)
4149 
4150 Input and output {#io}
4151 ================
4152 
4153 Reading and writing XML from/to files, streams and string buffers is done via
4154 the managing context by setting one of the following context members that
4155 control IO sources and sinks:
4156 
4157 ```cpp
4158 soap->recvfd = fd; // an int file descriptor to read from (0 by default)
4159 soap->sendfd = fd; // an int file descriptor to write to (1 by default)
4160 soap->is = &is; // C++ only: a std::istream is object to read from
4161 soap->os = &os; // C++ only: a std::ostream os object to write to
4162 soap->is = cs; // C only: a const char* string to read from (soap->is will advance)
4163 soap->os = &cs; // C only: pointer to a const char*, will be set to point to the string output
4164 ```
4165 
4166 Normally, all of these context members are NULL, which is required to send and
4167 receive data over sockets by gSOAP clients and servers. Therefore, if you set
4168 any of these context members in a client or server application then you MUST
4169 reset them to NULL to ensure that socket communications are not blocked.
4170 
4171 Note: the use of `soap->is` and `soap->os` in C requires gSOAP 2.8.28 or later.
4172 
4173 In the following sections, we present more details on how to read and write to
4174 files and streams, and use string buffers as sources and sinks for XML data.
4175 
4176 In addition, you can set IO callback functions to handle IO at a lower level.
4177 
4178 For more details, see the [gSOAP user guide.](http://www.genivia.com/doc/soapdoc2.html)
4179 
4180 🔝 [Back to table of contents](#)
4181 
4182 Reading and writing from/to files and streams {#io1}
4183 ---------------------------------------------
4184 
4185 The default IO is standard input and output. Other sources and sinks (those
4186 listed above) will be used until you (re)set them. For example with file-based
4187 input and output:
4188 
4189 ```cpp
4190 FILE *fp = fopen("record.xml", "r");
4191 if (fp != NULL)
4192 {
4193  soap->recvfd = fileno(fp); // get file descriptor of file to read from
4194  if (soap_read_ns__record(soap, &pers1))
4195  ... // handle IO error
4196  fclose(fp);
4197  soap->recvfd = 0; // read from stdin, or -1 to block reading
4198 }
4199 
4200 FILE *fp = fopen("record.xml", "w");
4201 if (fp != NULL)
4202 {
4203  soap->sendfd = fileno(fp); // get file descriptor of file to write to
4204  if (soap_write_ns__record(soap, &pers1))
4205  ... // handle IO error
4206  fclose(fp);
4207  soap->sendfd = 1; // write to stdout, or -1 to block writing
4208 }
4209 ```
4210 
4211 Similar code with streams in C++:
4212 
4213 ```cpp
4214 #include <fstream>
4215 
4216 std::fstream fs;
4217 fs.open("record.xml", std::ios::in);
4218 if (fs)
4219 {
4220  soap->is = &fs;
4221  if (soap_read__ns__record(soap, &pers1))
4222  ... // handle IO error
4223  fs.close();
4224  soap->is = NULL;
4225 }
4226 
4227 fs.open("record.xml", std::ios::out);
4228 if (fs)
4229 {
4230  soap->os = &fs;
4231  if (soap_write__ns__record(soap, &pers1))
4232  ... // handle IO error
4233  fs.close();
4234  soap->os = NULL;
4235 }
4236 ```
4237 
4238 🔝 [Back to table of contents](#)
4239 
4240 Reading and writing from/to string buffers {#io2}
4241 ------------------------------------------
4242 
4243 For C++ we recommend to use `std::stringstream` objects from `<sstream>` as
4244 illustrated in the following example:
4245 
4246 ```cpp
4247 #include <sstream>
4248 
4249 std::stringstream ss;
4250 ss.str("..."); // XML to parse
4251 soap->is = &ss;
4252 if (soap_read__ns__record(soap, &pers1))
4253  ... // handle IO error
4254 soap->is = NULL;
4255 
4256 soap->os = &ss;
4257 if (soap_write__ns__record(soap, &pers1))
4258  ... // handle IO error
4259 soap->os = NULL;
4260 std::string s = ss.str(); // string with XML
4261 ```
4262 
4263 For C we can use `soap->is` and `soap->os` to point to strings of XML content
4264 as follows (this requires gSOAP 2.8.28 or later):
4265 
4266 ```cpp
4267 soap->is = "..."; // XML to parse
4268 if (soap_read__ns__record(soap, &pers1))
4269  ... // handle IO error
4270 soap->is = NULL;
4271 
4272 const char *cs = NULL;
4273 soap->os = &cs;
4274 if (soap_write__ns__record(soap, &pers1))
4275  ... // handle IO error
4276 soap->os = NULL;
4277 ... = cs; // string with XML (do not free(cs): managed by the context and freed with soap_end())
4278 ```
4279 
4280 Note that `soap->os` is a pointer to a `const char*` string. The pointer is
4281 set by the managing context to point to the XML data that is stored on the
4282 context-managed heap.
4283 
4284 For earlier gSOAP versions we recommend to use IO callbacks `soap->frecv` and
4285 `soap->fsend`, see the [gSOAP user guide.](http://www.genivia.com/doc/soapdoc2.html)
4286 
4287 🔝 [Back to table of contents](#)
4288 
4289 Memory management {#memory}
4290 =================
4291 
4292 Memory management with the `soap` context enables us to allocate data in
4293 context-managed heap space that can be collectively deleted. All deserialized
4294 data is placed on the context-managed heap by the gSOAP engine.
4295 
4296 🔝 [Back to table of contents](#)
4297 
4298 Memory management in C {#memory1}
4299 ----------------------
4300 
4301 When working with gSOAP in C (i.e. using wsdl2h option `-c` and soapcpp2 option
4302 `-c`), data is allocated on the managed heap with:
4303 
4304 - `void *soap_malloc(struct soap*, size_t len)`.
4305 
4306 You can also make shallow copies of data with `soap_memdup` that uses
4307 `soap_malloc` and a safe version of `memcpy` to copy a chunk of data `src` with
4308 length `len` to the context-managed heap:
4309 
4310 - `void * soap_memdup(struct soap*, const void *src, size_t len)`
4311 
4312 This function returns a pointer to the copy. This function requires gSOAP
4313 2.8.27 or later.
4314 
4315 In gSOAP 2.8.35 and later, you can use an auto-generated function to allocate
4316 and initialize data of type `T` on the managed heap:
4317 
4318 - `T * soap_new_T(struct soap*, int n)`
4319 
4320 This function returns an array of length `n` of type `T` data that is default
4321 initialized (by internally calling `soap_malloc(soap, n * sizeof(T))` and then
4322 `soap_default_T(soap, T*)` on each array value). Use `n=1` to allocate and
4323 initialize a single value.
4324 
4325 The `soap_malloc` function is a wrapper around `malloc`, but which also permits
4326 the `struct soap` context to track all heap allocations for collective deletion
4327 with `soap_end(soap)`:
4328 
4329 ```cpp
4330 #include "soapH.h"
4331 #include "ns.nsmap"
4332 ...
4333 struct soap *soap = soap_new(); // new context
4334 ...
4335 struct ns__record *record = (struct ns__record*)soap_malloc(soap, sizeof(struct ns__record));
4336 soap_default_ns__record(soap, record); // auto-generated struct initializer
4337 ...
4338 soap_destroy(soap); // only for C++, see section on C++ below
4339 soap_end(soap); // delete record and all other heap allocations
4340 soap_free(soap); // delete context
4341 ```
4342 
4343 All data on the managed heap is mass-deleted with `soap_end(soap)` which must
4344 be called before `soap_done(soap)` or `soap_free(soap)`, which end the use of
4345 the `soap` engine context and free the context, respectively. Use
4346 `soap_free(soap)` only when the context is allocated with `soap_new()`. Use
4347 `soap_done(soap)` only when the context is stack allocated (so cannot be
4348 deleted from the heap).
4349 
4350 The managed heap is checked for memory leaks when the gSOAP code is compiled
4351 with `-DDEBUG`.
4352 
4353 The soapcpp2 auto-generated deserializers in C use `soap_malloc` to allocate
4354 and populate deserialized structures, which are managed by the context for
4355 collective deletion.
4356 
4357 To make `char*` and `wchar_t*` string copies to the context-managed heap, we
4358 can use the functions:
4359 
4360 - `char *soap_strdup(struct soap*, const char *str)` and
4361 - `wchar_t *soap_wstrdup(struct soap*, const wchar_t *wstr)`.
4362 
4363 If your C compiler supports `typeof` then you can use the following macro to
4364 simplify the managed heap allocation and initialization of primitive values:
4365 
4366 ```cpp
4367 #define soap_assign(soap, lhs, rhs) (*(lhs = (typeof(lhs))soap_malloc(soap, sizeof(*lhs))) = rhs)
4368 ```
4369 
4370 Pointers to primitive values are often used for optional members. For example,
4371 assume we have the following struct:
4372 
4373 ```cpp
4374 struct ns__record
4375 {
4376  const char *name; // required name
4377  uint64_t *SSN; // optional SSN
4378  struct ns__record *spouse; // optional spouse
4379 };
4380 ```
4381 
4382 Use `soap_assign` to create a SSN value on the managed heap:
4383 
4384 ```cpp
4385 struct soap *soap = soap_new(); // new context
4386 ...
4387 struct ns__record *record = (struct ns__record*)soap_malloc(soap, sizeof(struct ns__record));
4388 soap_default_ns__record(soap, record);
4389 record->name = soap_strdup(soap, "Joe");
4390 soap_assign(soap, record->SSN, 1234567890UL);
4391 ...
4392 soap_end(soap); // delete managed soap_malloc'ed heap data
4393 soap_free(soap); // delete context
4394 ```
4395 
4396 Without the `soap_assign` macro, you will need two lines of code, one to
4397 allocate and one to assign (you should also use this if your system can run out
4398 of memory):
4399 
4400 ```cpp
4401 assert((record->SSN = (uint64_t*)soap_malloc(soap, sizeof(utint64_t))) != NULL);
4402 *record->SSN = 1234567890UL;
4403 ```
4404 
4405 The gSOAP serializer can serialize any heap, stack, or static allocated data.
4406 So we can also create a new record as follows:
4407 
4408 ```cpp
4409 struct soap *soap = soap_new(); // new context
4410 ...
4411 struct ns__record *record = (struct ns__record*)soap_malloc(soap, sizeof(struct ns__record));
4412 static uint64_t SSN = 1234567890UL;
4413 soap_default_ns__record(soap, record);
4414 record->name = "Joe";
4415 record->SSN = &SSN; // safe to use static values: the value of record->SSN is never changed by gSOAP
4416 ...
4417 soap_end(soap); // delete managed soap_malloc'ed heap data
4418 soap_free(soap); // delete context
4419 ```
4420 
4421 Use the soapcpp2 auto-generated `soap_dup_T` functions to duplicate data into
4422 another context (this requires soapcpp2 option `-Ec` to generate), here shown
4423 for C with the second argument `dst` NULL because we want to allocate a new
4424 managed structure:
4425 
4426 ```cpp
4427 struct soap *other_soap = soap_new(); // another context
4428 struct ns__record *other_record = soap_dup_ns__record(other_soap, NULL, record);
4429 ...
4430 soap_destroy(other_soap); // only for C++, see section on C++ below
4431 soap_end(other_soap); // delete other_record and all of its deep data
4432 soap_free(other_soap); // delete context
4433 ```
4434 
4435 Note that the only reason to use another context and not to use the primary
4436 context is when the primary context must be destroyed together with all of the
4437 objects it manages while some of the objects must be kept alive. If the objects
4438 that are kept alive contain deep cycles then this is the only option we have,
4439 because deep copy with a managing context detects and preserves these
4440 cycles unless the `SOAP_XML_TREE` flag is used with the context:
4441 
4442 ```cpp
4443 struct soap *other_soap = soap_new1(SOAP_XML_TREE); // another context
4444 struct ns__record *other_record = soap_dup_ns__record(other_soap, NULL, record);
4445 ```
4446 
4447 The resulting deep copy will be a full copy of the source data structure as a
4448 tree without co-referenced data (i.e. no digraph) and without cycles. Cycles
4449 are pruned and (one of the) pointers that forms a cycle is repaced by NULL.
4450 
4451 You can also deep copy into unmanaged space and use the auto-generated
4452 `soap_del_T()` function (requires soapcpp2 option `-Ed` to generate) to delete
4453 it later, but you MUST NOT do this for any data that has deep cycles in its
4454 runtime data structure:
4455 
4456 ```cpp
4457 struct ns__record *other_record = soap_dup_ns__record(NULL, NULL, record);
4458 ...
4459 soap_del_ns__record(other_record); // deep delete record data members
4460 free(other_record); // delete the record
4461 ```
4462 
4463 Cycles in the data structure will lead to non-termination when making unmanaged
4464 deep copies. Consider for example:
4465 
4466 ```cpp
4467 struct ns__record
4468 {
4469  const char *name; // required name
4470  uint64_t SSN; // required SSN
4471  struct ns__record *spouse; // optional spouse
4472 };
4473 ```
4474 
4475 The code to populate a structure with a mutual spouse relationship:
4476 
4477 ```cpp
4478 struct soap *soap = soap_new();
4479 ...
4480 struct ns__record pers1, pers2;
4481 soap_default_ns__record(soap, &pers1);
4482 soap_default_ns__record(soap, &pers2);
4483 pers1.name = "Joe"; // OK to serialize static data
4484 pers1.SSN = 1234567890;
4485 pers1.spouse = &pers2;
4486 pers2.name = soap_strdup(soap, "Jane"); // allocates and copies a string
4487 pers2.SSN = 1987654320;
4488 pers2.spouse = &pers1;
4489 ...
4490 struct ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &pers1); // BAD
4491 struct ns__record *pers4 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4492 soap_set_mode(soap, SOAP_XML_TREE);
4493 struct ns__record *pers5 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4494 ```
4495 
4496 As we can see, the gSOAP serializer can serialize any heap, stack, or static
4497 allocated data, such as in the code above. So we can serialize the
4498 stack-allocated `pers1` record as follows:
4499 
4500 ```cpp
4501 FILE *fp = fopen("record.xml", "w");
4502 if (fp != NULL)
4503 {
4504  soap->sendfd = fileno(fp); // file descriptor to write to
4505  soap_set_mode(soap, SOAP_XML_GRAPH); // support id-ref w/o requiring SOAP
4506  soap_clr_mode(soap, SOAP_XML_TREE); // if set, clear
4507  soap_write_ns__record(soap, &pers1);
4508  fclose(fp);
4509  soap->sendfd = -1; // block further writing
4510 }
4511 ```
4512 
4513 which produces an XML document record.xml that is similar to:
4514 
4515 <div class="alt">
4516 ```xml
4517 <ns:record xmlns:ns="urn:types" id="Joe">
4518  <name>Joe</name>
4519  <SSN>1234567890</SSN>
4520  <spouse id="Jane">
4521  <name>Jane</name>
4522  <SSN>1987654320</SSN>
4523  <spouse ref="#Joe"/>
4524  </spouse>
4525 </ns:record>
4526 ```
4527 </div>
4528 
4529 Deserialization of an XML document with a SOAP 1.1/1.2 encoded id-ref graph
4530 leads to the same non-termination problem when we later try to copy the data
4531 into unmanaged memory heap space:
4532 
4533 ```cpp
4534 struct soap *soap = soap_new1(SOAP_XML_GRAPH); // support id-ref w/o SOAP
4535 ...
4536 struct ns__record pers1;
4537 FILE *fp = fopen("record.xml", "r");
4538 if (fp != NULL)
4539 {
4540  soap->recvfd = fileno(fp);
4541  if (soap_read_ns__record(soap, &pers1))
4542  ... // handle IO error
4543  fclose(fp);
4544  soap->recvfd = -1; // blocks further reading
4545 }
4546 ...
4547 struct ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &pers1); // BAD
4548 struct ns__record *pers4 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4549 soap_set_mode(soap, SOAP_XML_TREE);
4550 struct ns__record *pers5 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4551 ```
4552 
4553 Copying data with `soap_dup_T(soap)` into managed heap memory space is always
4554 safe. Copying into unmanaged heap memory space requires diligence. But
4555 deleting unmanaged data is easy with `soap_del_T()`.
4556 
4557 You can also use `soap_del_T()` to delete structures that you created in C, but
4558 only if these structures are created with `malloc` and do NOT contain pointers
4559 to stack and static data.
4560 
4561 You can unlink one or more allocated objects from the managed heap to allow the
4562 object to live after `soap_end(soap)` by using:
4563 
4564 - `void soap_unlink(struct soap *soap, void *ptr)`
4565 
4566 The unlinked heap-allocated data pointed to by `ptr` can be accessed after
4567 `soap_end(soap)`. Do not forget to free the data with `free(ptr)`. Be aware
4568 that `soap_unlink(soap, ptr)` does not perform a deep unlinkage. If `ptr` is a
4569 struct, pointer members will become invalid when pointing to objects on the
4570 managed heap. Use `soap_unlink(soap, ptr->member)` to unlink `member` as well.
4571 
4572 Finally, when data is allocated in managed memory heap space, either explicitly
4573 with the allocation functions shown above or by the gSOAP deserializers, you
4574 can delegate the management and deletion of this data to another `struct soap`
4575 context. That context will be responsible to delete the data with
4576 `soap_end(soap)` later:
4577 
4578 - `void delegate_deletion(struct soap *soap_from, struct soap *soap_to)`
4579 
4580 This allows the `soap_from` context to be deleted with `soap_free(soap_from)`
4581 (assuming it is allocated with `soap_new()`, use `soap_done(soap_from)` when
4582 `soap_from` is stack-allocated) while the managed data remains intact. You
4583 can use this function any time, to delegate management and deletion to another
4584 context `soap_to` and then continue with the current context. You can also use
4585 different source `soap_from` contexts to delegate management and deletion to
4586 the other `soap_to` context. To mass delete all managed data, use
4587 `soap_end(soap_to)`.
4588 
4589 🔝 [Back to table of contents](#)
4590 
4591 Memory management in C++ {#memory2}
4592 ------------------------
4593 
4594 When working with gSOAP in C++, the gSOAP engine allocates data on a managed
4595 heap using `soap_new_T(soap)` to allocate a type with type name `T`. Managed
4596 heap allocation is tracked by the `struct soap` context for collective deletion
4597 with `soap_destroy(soap)` for structs, classes, and templates and with
4598 `soap_end(soap)` for everything else.
4599 
4600 You should only use `soap_malloc(struct soap*, size_t len)` to allocate
4601 primitive types, but `soap_new_T()` is preferred. The auto-generated `T *
4602 soap_new_T(struct soap*)` returns data allocated on the managed heap for type
4603 `T`. The data is mass-deleted with `soap_destroy(soap)` followed by
4604 `soap_end(soap)`.
4605 
4606 The `soap_new_T` functions return NULL when allocation fails. C++ exceptions
4607 are never raised by gSOAP code when data is allocated, unless `SOAP_NOTHROW`
4608 (set to `(std::nothrow)`) is redefined to permit `new` to throw exceptions.
4609 
4610 There are four variations of `soap_new_T()` to allocate data of type `T` that
4611 soapcpp2 auto-generates:
4612 
4613 - `T * soap_new_T(struct soap*)` returns a new instance of `T` that is default
4614  initialized. For classes, initialization is internally performed using the
4615  soapcpp2 auto-generated `void T::soap_default(struct soap*)` method of the
4616  class, but ONLY IF the soapcpp2 auto-generated default constructor is used
4617  that invokes `soap_default()` and was not replaced by a user-defined default
4618  constructor.
4619 
4620 - `T * soap_new_T(struct soap*, int n)` returns an array of `n` new instances of
4621  `T`. The instances in the array are default initialized as described above.
4622 
4623 - `T * soap_new_req_T(struct soap*, ...)` (structs and classes only) returns a
4624  new instance of `T` and sets the required data members to the values
4625  specified in `...`. The required data members are those with nonzero
4626  minOccurs, see the subsections on
4627  [(smart) pointer members and their occurrence constraints](#toxsd9-8) and
4628  [container and array members and their occurrence constraints](#toxsd9-9).
4629 
4630 - `T * soap_new_set_T(struct soap*, ...)` (structs and classes only) returns a
4631  new instance of `T` and sets the public/serializable data members to the values
4632  specified in `...`.
4633 
4634 The above functions can be invoked with a NULL `soap` context, but you are then
4635 responsible to use `delete T` to remove this instance from the unmanaged heap.
4636 
4637 For example, to allocate a managed `std::string` you can use:
4638 
4639 ```cpp
4640 std::string *s = soap_new_std__string(soap);
4641 ```
4642 
4643 Primitive types and arrays of these are allocated with `soap_malloc`
4644 (`soap_new_T` calls `soap_malloc` for primitive type `T`). All primitive types
4645 (i.e. no classes, structs, class templates, containers, and smart pointers) are
4646 allocated with `soap_malloc` for reasons of efficiency.
4647 
4648 You can use a C++ template to simplify the managed allocation and initialization
4649 of primitive values as follows (this is for primitive types only):
4650 
4651 ```cpp
4652 template<class T>
4653 T * soap_make(struct soap *soap, T val) throw (std::bad_alloc)
4654 {
4655  T *p = (T*)soap_malloc(soap, sizeof(T));
4656  if (p == NULL)
4657  throw std::bad_alloc;
4658  *p = val;
4659  return p;
4660 }
4661 ```
4662 
4663 For example, assuming we have the following class:
4664 
4665 ```cpp
4666 class ns__record
4667 {
4668  public:
4669  std::string name; // required name
4670  uint64_t *SSN; // optional SSN
4671  ns__record *spouse; // optional spouse
4672 };
4673 ```
4674 
4675 You can instantiate a record by using the auto-generated
4676 `soap_new_set_ns__record` and use `soap_make` to create a SSN value on the
4677 managed heap as follows:
4678 
4679 ```cpp
4680 soap *soap = soap_new(); // new context
4681 ...
4682 ns__record *record = soap_new_set_ns__record(
4683  soap,
4684  "Joe",
4685  soap_make<uint64_t>(soap, 1234567890UL),
4686  NULL);
4687 ...
4688 soap_destroy(soap); // delete record and all other managed instances
4689 soap_end(soap); // delete managed soap_malloc'ed heap data
4690 soap_free(soap); // delete context
4691 ```
4692 
4693 All data on the managed heap is mass-deleted with `soap_end(soap)` which must
4694 be called before `soap_done(soap)` or `soap_free(soap)`, which end the use of
4695 the `soap` engine context and free the context, respectively. Use
4696 `soap_free(soap)` only when the context is allocated with `soap_new()`. Use
4697 `soap_done(soap)` only when the context is stack allocated (so cannot be
4698 deleted from the heap).
4699 
4700 The managed heap is checked for memory leaks when the gSOAP code is compiled
4701 with `-DDEBUG`.
4702 
4703 Note however that the gSOAP serializer can serialize any heap, stack, or static
4704 allocated data. So we can also create a new record as follows:
4705 
4706 ```cpp
4707 uint64_t SSN = 1234567890UL;
4708 ns__record *record = soap_new_set_ns__record(soap, "Joe", &SSN, NULL);
4709 ```
4710 
4711 which will be fine to serialize this record as long as the local `SSN`
4712 stack-allocated value remains in scope when invoking the serializer and/or
4713 using `record`. It does not matter if `soap_destroy` and `soap_end` are called
4714 beyond the scope of `SSN`.
4715 
4716 To facilitate class methods to access the managing context, we can add a soap
4717 context pointer to a class/struct:
4718 
4719 ```cpp
4720 class ns__record
4721 {
4722  ...
4723  void create_more(); // needs a context to create more internal data
4724  protected:
4725  struct soap *soap; // the context that manages this instance, or NULL
4726 };
4727 ```
4728 
4729 The context is set when invoking `soap_new_T` (and similar) with a non-NULL
4730 context argument.
4731 
4732 You can also use a template when an array of pointers to values is required.
4733 To create an array of pointers to values, define the following template:
4734 
4735 ```cpp
4736 template<class T>
4737 T **soap_make_array(struct soap *soap, T* array, int n) throw (std::bad_alloc)
4738 {
4739  T **p = (T**)soap_malloc(soap, n * sizeof(T*));
4740  if (p == NULL)
4741  throw std::bad_alloc;
4742  for (int i = 0; i < n; ++i)
4743  p[i] = &array[i];
4744  return p;
4745 }
4746 ```
4747 
4748 The `array` parameter is a pointer to an array of `n` values. The template
4749 returns an array of `n` pointers that point to the values in that array:
4750 
4751 ```cpp
4752 // create an array of 100 pointers to 100 records
4753 int n = 100;
4754 ns__record **precords = soap_make_array(soap, soap_new_ns__record(soap, n), n);
4755 for (int i = 0; i < n; ++i)
4756 {
4757  precords[i]->name = "...";
4758  precords[i]->SSN = soap_make<uint64_t>(1234567890UL + i);
4759 }
4760 ```
4761 
4762 Note that `soap_new_ns__record(soap, n)` returns a pointer to an array of `n`
4763 records, which is then used to create an array of `n` pointers to these records.
4764 
4765 Use the soapcpp2 auto-generated `soap_dup_T` functions to duplicate data into
4766 another context (this requires soapcpp2 option `-Ec` to generate), here shown
4767 for C++ with the second argument `dst` NULL to allocate a new managed object:
4768 
4769 ```cpp
4770 soap *other_soap = soap_new(); // another context
4771 ns__record *other_record = soap_dup_ns__record(other_soap, NULL, record);
4772 ...
4773 soap_destroy(other_soap); // delete record and other managed instances
4774 soap_end(other_soap); // delete other data (the SSNs on the heap)
4775 soap_free(other_soap); // delete context
4776 ```
4777 
4778 To duplicate base and derived instances when a base class pointer or reference
4779 is provided, use the auto-generated method `T * T::soap_dup(struct soap*)`:
4780 
4781 ```cpp
4782 soap *other_soap = soap_new(); // another context
4783 ns__record *other_record = record->soap_dup(other_soap);
4784 ...
4785 soap_destroy(other_soap); // delete record and other managed instances
4786 soap_end(other_soap); // delete other data (the SSNs on the heap)
4787 soap_free(other_soap); // delete context
4788 ```
4789 
4790 Note that the only reason to use another context and not to use the primary
4791 context is when the primary context must be destroyed together with all of the
4792 objects it manages while some of the objects must be kept alive. If the objects
4793 that are kept alive contain deep cycles then this is the only option we have,
4794 because deep copy with a managing context detects and preserves these
4795 cycles unless the `SOAP_XML_TREE` flag is used with the context:
4796 
4797 ```cpp
4798 soap *other_soap = soap_new1(SOAP_XML_TREE); // another context
4799 ns__record *other_record = record->soap_dup(other_soap); // deep tree copy
4800 ```
4801 
4802 The resulting deep copy will be a full copy of the source data structure as a
4803 tree without co-referenced data (i.e. no digraph) and without cycles. Cycles
4804 are pruned and (one of the) pointers that forms a cycle is repaced by NULL.
4805 
4806 You can also deep copy into unmanaged space and use the auto-generated
4807 `soap_del_T()` function or the `T::soap_del()` method (requires soapcpp2 option
4808 `-Ed` to generate) to delete it later, but we MUST NOT do this for any data
4809 that has deep cycles in its runtime data structure graph:
4810 
4811 ```cpp
4812 ns__record *other_record = record->soap_dup(NULL);
4813 ...
4814 other_record->soap_del(); // deep delete record data members
4815 delete other_record; // delete the record
4816 ```
4817 
4818 Cycles in the data structure will lead to non-termination when making unmanaged
4819 deep copies. Consider for example:
4820 
4821 ```cpp
4822 class ns__record
4823 {
4824  const char *name; // required name
4825  uint64_t SSN; // required SSN
4826  ns__record *spouse; // optional spouse
4827 };
4828 ```
4829 
4830 The code to populate a structure with a mutual spouse relationship:
4831 
4832 ```cpp
4833 soap *soap = soap_new();
4834 ...
4835 ns__record pers1, pers2;
4836 pers1.name = "Joe";
4837 pers1.SSN = 1234567890;
4838 pers1.spouse = &pers2;
4839 pers2.name = "Jane";
4840 pers2.SSN = 1987654320;
4841 pers2.spouse = &pers1;
4842 ...
4843 ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &pers1); // BAD
4844 ns__record *pers4 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4845 soap_set_mode(soap, SOAP_XML_TREE);
4846 ns__record *pers5 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4847 ```
4848 
4849 Note that the gSOAP serializer can serialize any heap, stack, or static
4850 allocated data, such as in the code above. So we can serialize the
4851 stack-allocated `pers1` record as follows:
4852 
4853 ```cpp
4854 FILE *fp = fopen("record.xml", "w");
4855 if (fp != NULL)
4856 {
4857  soap->sendfd = fileno(fp); // file descriptor to write to
4858  soap_set_mode(soap, SOAP_XML_GRAPH); // support id-ref w/o requiring SOAP
4859  soap_clr_mode(soap, SOAP_XML_TREE); // if set, clear
4860  if (soap_write_ns__record(soap, &pers1))
4861  ... // handle IO error
4862  fclose(fp);
4863  soap->sendfd = -1; // block further writing
4864 }
4865 ```
4866 
4867 which produces an XML document record.xml that is similar to:
4868 
4869 <div class="alt">
4870 ```xml
4871 <ns:record xmlns:ns="urn:types" id="Joe">
4872  <name>Joe</name>
4873  <SSN>1234567890</SSN>
4874  <spouse id="Jane">
4875  <name>Jane</name>
4876  <SSN>1987654320</SSN>
4877  <spouse ref="#Joe"/>
4878  </spouse>
4879 </ns:record>
4880 ```
4881 </div>
4882 
4883 Deserialization of an XML document with a SOAP 1.1/1.2 encoded id-ref graph
4884 leads to the same non-termination problem when we later try to copy the data
4885 into unmanaged space:
4886 
4887 ```cpp
4888 soap *soap = soap_new1(SOAP_XML_GRAPH); // support id-ref w/o SOAP
4889 ...
4890 ns__record pers1;
4891 FILE *fp = fopen("record.xml", "r");
4892 if (fp != NULL)
4893 {
4894  soap->recvfd = fileno(fp); // file descriptor to read from
4895  if (soap_read_ns__record(soap, &pers1))
4896  ... // handle IO error
4897  fclose(fp);
4898  soap->recvfd = -1; // block further reading
4899 }
4900 ...
4901 ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &pers1); // BAD
4902 ns__record *pers4 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4903 soap_set_mode(soap, SOAP_XML_TREE);
4904 ns__record *pers5 = soap_dup_ns__record(soap, NULL, &pers1); // OK
4905 ```
4906 
4907 Copying data with `soap_dup_T(soap)` into managed space is always safe. Copying
4908 into unmanaged space requires diligence. But deleting unmanaged data is easy
4909 with `soap_del_T()`.
4910 
4911 You can also use `soap_del_T()` to delete structures in C++, but only if these
4912 structures are created with `new` (and `new []` for arrays when applicable) for
4913 classes, structs, and class templates and with `malloc` for anything else, and
4914 the structures do NOT contain pointers to stack and static data.
4915 
4916 You can unlink one or more allocated objects from the managed heap to allow the
4917 object to live after `soap_destroy(soap)` and `soap_end(soap)` by using:
4918 
4919 - `void soap_unlink(struct soap *soap, void *ptr)`
4920 
4921 The unlinked heap-allocated data pointed to by `ptr` can be accessed after
4922 `soap_destroy(soap)` and `soap_end(soap)`. Do not forget to free the data with
4923 `delete ptr` (C++ class instance only) or with `free(ptr)` (non-class data).
4924 Be aware that `soap_unlink(soap, ptr)` does not perform a deep unlinkage. If
4925 `ptr` is a struct or class, pointer members will become invalid when pointing
4926 to objects on the managed heap. Use `soap_unlink(soap, ptr->member)` to unlink
4927 `member` as well.
4928 
4929 Finally, when data is allocated in managed memory heap space, either explicitly
4930 with the allocation functions shown above or by the gSOAP deserializers, you
4931 can delegate the management and deletion of this data to another `struct soap`
4932 context. That context will be responsible to delete the data with
4933 `soap_destroy(soap)` and `soap_end(soap)` later:
4934 
4935 - `void delegate_deletion(struct soap *soap_from, struct soap *soap_to)`
4936 
4937 This allows the `soap_from` context to be deleted with `soap_free(soap_from)`
4938 (assuming it is allocated with `soap_new()`, use `soap_done(soap_from)` when
4939 `soap_from` is stack-allocated) while the managed data remains intact. You
4940 can use this function any time, to delegate management and deletion to another
4941 context `soap_to` and then continue with the current context. You can also use
4942 different source `soap_from` contexts to delegate management and deletion to
4943 the other `soap_to` context. To mass delete all managed data, use
4944 `soap_destroy(soap_to)` followed by `soap_end(soap_to)`.
4945 
4946 🔝 [Back to table of contents](#)
4947 
4948 Context flags to initialize the soap struct {#flags}
4949 ===========================================
4950 
4951 There are several context initialization flags and context mode flags to
4952 control XML serialization at runtime. The flags are set with `soap_new1()` to
4953 allocate and initialize a new context:
4954 
4955 ```cpp
4956 struct soap *soap = soap_new1(<flag> | <flag> ... | <flag>);
4957 ...
4958 soap_destroy(soap); // delete objects
4959 soap_end(soap); // delete other data and temp data
4960 soap_free(soap); // free context
4961 ```
4962 
4963 and with `soap_init1()` for stack-allocated contexts:
4964 
4965 ```cpp
4966 struct soap soap;
4967 soap_init1(&soap, <flag> | <flag> ... | <flag>);
4968 ...
4969 soap_destroy(&soap); // delete objects
4970 soap_end(&soap); // delete other data and temp data
4971 soap_done(&soap); // clear context
4972 ```
4973 
4974 where `<flag>` is one of:
4975 
4976 - `SOAP_C_UTFSTRING`: enables all `std::string` and `char*` strings to
4977  contain UTF-8 content. This option is recommended.
4978 
4979 - `SOAP_C_NILSTRING`: treat empty strings as if they were NULL pointers, i.e.
4980  omits elements and attributes when empty.
4981 
4982 - `SOAP_XML_STRICT`: strictly validates XML while deserializing. Should not be
4983  used together with SOAP 1.1/1.2 encoding style of messaging. Use soapcpp2
4984  option `-s` to hard code `SOAP_XML_STRICT` in the generated serializers. Not
4985  recommended with SOAP 1.1/1.2 encoding style messaging.
4986 
4987 - `SOAP_XML_INDENT`: produces indented XML.
4988 
4989 - `SOAP_XML_CANONICAL`: c14n canonocalization, removes unused `xmlns` bindings
4990  and adds them to appropriate places by applying c14n normalization rules.
4991  Should not be used together with SOAP 1.1/1.2 encoding style messaging.
4992 
4993 - `SOAP_XML_TREE`: write tree XML without id-ref, while pruning data structure
4994  cycles to prevent nontermination of the serializer for cyclic structures.
4995 
4996 - `SOAP_XML_GRAPH`: write graph (digraph and cyclic graphs with shared pointers
4997  to objects) using id-ref attributes. That is, XML with SOAP multi-ref
4998  encoded id-ref elements. This is a structure-preserving serialization format,
4999  because co-referenced data and also cyclic relations are accurately represented.
5000 
5001 - `SOAP_XML_DEFAULTNS`: uses xmlns default namespace declarations, assuming
5002  that the schema attribute form is "qualified" by default (be warned if it is
5003  not, since attributes in the null namespace will get bound to namespaces!).
5004 
5005 - `SOAP_XML_NIL`: emit empty element with `xsi:nil` for all NULL pointers
5006  serialized.
5007 
5008 - `SOAP_XML_IGNORENS`: the XML parser ignores XML namespaces, i.e. element and
5009  attribute tag names match independent of their namespace.
5010 
5011 - `SOAP_XML_NOTYPE`: removes all `xsi:type` attribuation. This option is usually
5012  not needed unless the receiver rejects all `xsi:type` attributes. This option
5013  may affect the quality of the deserializer, which relies on `xsi:type`
5014  attributes to distinguish base class instances from derived class instances
5015  transported in the XML payloads.
5016 
5017 - `SOAP_IO_CHUNK`: to enable HTTP chunked transfers.
5018 
5019 - `SOAP_IO_STORE`: full buffering of outbound messages.
5020 
5021 - `SOAP_ENC_ZLIB`: compress messages, requires compiling with `-DWITH_GZIP` and
5022  linking with zlib (`-lz`).
5023 
5024 - `SOAP_ENC_MIME`: enable MIME attachments, see
5025  [MIME/MTOM attachment binary types](#toxsd10-3).
5026 
5027 - `SOAP_ENC_MTOM`: enable MTOM attachments, see
5028  [MIME/MTOM attachment binary types](#toxsd10-3).
5029 
5030 @note C++ Web service proxy and service classes have their own context, either
5031 as a base class (soapcpp2 option -i) or as a data member `soap` that points to
5032 a context (soapcpp2 option -j). These contexts are allocated when the proxy or
5033 service is instantiated with context flags that are passed to the constructor.
5034 
5035 🔝 [Back to table of contents](#)
5036 
5037 Context parameter settings {#params}
5038 ==========================
5039 
5040 After allocation and initializtion of a `struct soap` context, several context
5041 parameters can be set (some parameters may require 2.8.31 and later versions):
5042 
5043 - `unsigned int soap::maxlevel` is the maximum XML nesting depth levels that
5044  the parser permits. Default initialized to `SOAP_MAXLEVEL` (10000), which is
5045  a redefinable macro in stdsoap2.h. Set `soap::maxlevel` to a lower value to
5046  restrict XML parsing nesting depth.
5047 
5048 - `long soap::maxlength` is the maximum string content length if not already
5049  constrained by an XML schema validation `maxLength` constraint. Zero means
5050  unlimited string lengths are permitted (unless restricted by XML schema
5051  `maxLength`). Default initialized to `SOAP_MAXLENGTH` (0), which is a
5052  redefinable macro in stdsoap2.h. Set `soap::maxlength` to a positive value
5053  to restrict the number of (wide) characters in strings parsed, restrict
5054  hexBinary byte length, and restrict base64Binary byte length.
5055 
5056 - `size_t soap::maxoccurs` is the maximum number of array or container elements
5057  permitted by the parser. Must be greater than zero (0). Default initialized
5058  to `SOAP_MAXOCCURS` (100000), which is a redefinable macro in stdsoap2.h.
5059  Set `soap::maxoccurs` to a positive value to restrict the number of array and
5060  container elements that can be parsed.
5061 
5062 - `soap::version` is the SOAP version used, with 0 for non-SOAP, 1 for SOAP1.1,
5063  and 2 for SOAP1.2. This value is normally set by web service operations, and
5064  is otherwise 0 (non-SOAP). Use `soap_set_version(struct soap*, short)` to
5065  set the value. This controls XML namespaces and SOAP id-ref serialization
5066  when applicable with an encodingStyle (see below).
5067 
5068 - `const char *soap::encodingStyle` is a string that is used with SOAP
5069  encoding, normally NULL for non-SOAP XML. Set this string to "" (empty
5070  string) to enable SOAP encoding style, which supports id-ref graph
5071  serialization (see also the `SOAP_XML_GRAPH` [context flag](#flags)).
5072 
5073 - `int soap::recvfd` is the file descriptor to read and parse source data from.
5074  Default initialized to 0 (stdin). See also [input and output](#io).
5075 
5076 - `int soap::sendfd` is the file descriptor to write data to. Default
5077  initialized to 1 (stdout). See also [input and output](#io).
5078 
5079 - `const char *is` for C: string to read and parse source data from, overriding
5080  the `recvfd` source. Normally NULL. This value must be reset to NULL or
5081  the parser will continue to read from this string content until the NUL
5082  character. See also [input and output](#io).
5083 
5084 - `std::istream *is` for C++: an input stream to read and parse source data
5085  from, overriding the `recvfd` source. Normally NULL. This value must be
5086  reset to NULL or the parser will continue to read from this stream until EOF.
5087  See also [input and output](#io).
5088 
5089 - `const char **os` for C: points to a string (a `const char *`) that will be
5090  set to point to the string output. Normally NULL. This value must be reset
5091  to NULL or the next output will result in reassigning the pointer to point to
5092  the next string that is output. The strings are automatically deallocated by
5093  `soap_end(soap)`. See also [input and output](#io).
5094 
5095 - `std::ostream *os` for C++: an output stream to write output to. Normally
5096  NULL. This value must be reste to NULL or the next output will be send to
5097  this stream. See also [input and output](#io).
5098 
5099 🔝 [Back to table of contents](#)
5100 
5101 Error handling and reporting {#errors}
5102 ============================
5103 
5104 The gSOAP API functions return `SOAP_OK` (zero) or a non-zero error code. The
5105 error code is stored in `int soap::error` of the current `struct soap` context.
5106 Error messages can be displayed with:
5107 
5108 - `void soap_stream_fault(struct soap*, std::ostream &os)` for C++ only, prints
5109  the error message to an output stream.
5110 
5111 - `void soap_print_fault(struct soap*, FILE *fd)` prints the error message to a
5112  FILE descriptor.
5113 
5114 - `void soap_sprint_fault(struct soap*, char *buf, size_t len)` saves the error
5115  message to a fixed-size buffer allocated with a maximum length.
5116 
5117 - `void soap_print_fault_location(struct soap*, FILE *fd)` prints the location
5118  and part of the XML where the parser encountered an error.
5119 
5120 C++ exceptions are never raised by gSOAP code, even when data is allocated.
5121 (That is unless the `SOAP_NOTHROW` macro (set to `(std::nothrow)` by default)
5122 is redefined to permit `new` to throw exceptions.)
5123 
5124 A `SOAP_EOM` error code is returned when memory was exhausted during
5125 processing of input and/or output of data.
5126 
5127 An EOF (`SOAP_EOF` or -1) error code is returned when the parser has hit EOF
5128 but expected more input, or when socket communications timed out. In addition
5129 to the `SOAP_EOF` error, the `int soap::errnum` of the `struct soap` context is
5130 set to the `errno` value of the operation that failed. For timeouts, the
5131 `soap::ernum` value is always 0 instead of an `errno` error code.
5132 
5133 Use `soap_xml_error_check(soap->error)` to check for XML errors. This returns
5134 true (non-zero) when a parsing and validation error has occurred.
5135 
5136 For example:
5137 
5138 ```cpp
5139 #include <sstream>
5140 
5141 struct soap *soap = soap_new1(SOAP_XML_INDENT | SOAP_XML_STRICT | SOAP_XML_TREE);
5142 struct ns__record person;
5143 std::stringstream ss;
5144 ss.str("..."); // XML to parse
5145 soap->is = &ss;
5146 if (soap_read__ns__record(soap, &person))
5147 {
5148  if (soap_xml_error_check(soap->error))
5149  std::cerr << "XML parsing error!" << std::endl;
5150  else
5151  soap_stream_fault(soap, std::cerr);
5152 }
5153 else
5154 {
5155  ... // all OK, use person record
5156 }
5157 soap_destroy(soap); // delete objects
5158 soap_end(soap); // delete other data and temp data
5159 soap_free(soap); // free context
5160 ```
5161 
5162 When deploying your application on UNIX and Linux systems, UNIX signal handlers
5163 should be added to your code handle signals, in particular `SIGPIPE`:
5164 
5165 ```cpp
5166 signal(SIGPIPE, sigpipe_handler);
5167 ```
5168 
5169 where the `sigpipe_handler` is a function:
5170 
5171 ```cpp
5172 void sigpipe_handler(int x) { }
5173 ```
5174 
5175 Other UNIX signals may have to be handled as well.
5176 
5177 The gSOAP engine is designed for easy memory cleanup after being interrupted.
5178 Use `soap_destroy(soap)` and `soap_end(soap)`, after which the `soap` context
5179 can be reused.
5180 
5181 🔝 [Back to table of contents](#)
5182 
5183 Features and limitations {#features}
5184 ========================
5185 
5186 In general, to use the generated code:
5187 
5188 - Make sure to `#include "soapH.h"` in your code and also define a namespace
5189  table or `#include "ns.nsmap"` with the generated table, where `ns` is the
5190  namespace prefix for services.
5191 
5192 - Use soapcpp2 option -j (C++ only) to generate C++ proxy and service objects.
5193  The auto-generated files include documented inferfaces. Compile with
5194  soapC.cpp and link with -lgsoap++, or alternatively compile stdsoap2.cpp.
5195 
5196 - Without soapcpp2 option -j: client-side uses the auto-generated
5197  soapClient.cpp and soapC.cpp (or C versions of those). Compile and link with
5198  -lgsoap++ (-lgsoap for C), or alternatively compile stdsoap2.cpp
5199  (stdsoap2.c for C).
5200 
5201 - Without soapcpp2 option -j: server-side uses the auto-generated
5202  soapServer.cpp and soapC.cpp (or C versions of those). Compile and link with
5203  -lgsoap++ (-lgsoap for C), or alternatively compile stdsoap2.cpp (stdsoap2.c
5204  for C).
5205 
5206 - Use `soap_new()` or `soap_new1(int flags)` to allocate and initialize a
5207  heap-allocated context with or without flags. Delete this context with
5208  `soap_free(struct soap*)`, but only after `soap_destroy(struct soap*)` and
5209  `soap_end(struct soap*)`.
5210 
5211 - Use `soap_init(struct *soap)` or `soap_init1(struct soap*, int flags)` to
5212  initialize a stack-allocated context with or without flags. End the use of
5213  this context with `soap_done(struct soap*)`, but only after
5214  `soap_destroy(struct soap*)` and `soap_end(struct soap*)`.
5215 
5216 Additional notes with respect to the wsdl2h and soapcpp2 tools:
5217 
5218 - Nested classes, structs, and unions in a gSOAP header file are unnested by
5219  soapcpp2.
5220 
5221 - Use `#import "file.h"` instead of `#include` to import other header files in
5222  a gSOAP header file for soapcpp2. The `#include`, `#define`, and `#pragma`
5223  are accepted by soapcpp2, but are moved to the very start of the generated
5224  code for the C/C++ compiler to include before all generated definitions.
5225  Often it is useful to add an `#include` with a [volatile type](#toxsd9-2)
5226  that includes the actual type declaration, and to ensure transient types are
5227  declared when these are used in a data binding interface declared in a gSOAP
5228  header file for soapcpp2.
5229 
5230 - To remove any SOAP-specific bindings, use soapcpp2 option `-0`.
5231 
5232 - A gSOAP header file for soapcpp2 should not include any code statements, only
5233  data type declarations. This includes constructor initialization lists that are
5234  not permitted. Use member initializations instead.
5235 
5236 - C++ namespaces are supported. Use wsdl2h option `-qname`. Or add a `namespace
5237  name { ... }` to the header file, but the `{ ... }` MUST cover the entire
5238  header file content from begin to end.
5239 
5240 - Optional XML DOM support can be used to store mixed content or literal XML
5241  content. Otherwise, mixed content may be lost. Use wsdl2h option `-d` for
5242  XML DOM support and compile and link with `dom.c` or `dom.cpp`. For details,
5243  see [XML DOM and XPath](http://www.genivia.com/doc/dom/html).
5244 
5245 🔝 [Back to table of contents](#)
5246 
5247 Removing SOAP namespaces from XML payloads {#nsmap}
5248 ==========================================
5249 
5250 The soapcpp2 tool generates a `.nsmap` file that includes two bindings for SOAP
5251 namespaces. We can remove all SOAP namespaces (and SOAP processing logic) with
5252 soapcpp2 option `-0` or by simply setting the two entries to NULL:
5253 
5254 ```cpp
5255 struct Namespace namespaces[] =
5256 {
5257  {"SOAP-ENV", NULL, NULL, NULL},
5258  {"SOAP-ENC", NULL, NULL, NULL},
5259  ...
5260 };
5261 ```
5262 
5263 Note that once the `.nsmap` is generated, you can copy-paste the content into
5264 your project code. However, if we rerun wsdl2h on updated WSDL/XSD files or
5265 `typemap.dat` declarations then we need to use the updated table.
5266 
5267 In cases that no XML namespaces are used at all, for example with
5268 [XML-RPC](http://www.genivia.com/doc/xml-rpc-json/html), you may use an empty
5269 namespace table:
5270 
5271 ```cpp
5272 struct Namespace namespaces[] = {{NULL,NULL,NULL,NULL}};
5273 ```
5274 
5275 However, beware that any built-in xsi attributes that are rendered will lack
5276 the proper namespace binding. At least we suggest to use `SOAP_XML_NOTYPE` for
5277 this reason.
5278 
5279 🔝 [Back to table of contents](#)
5280 
5281 Examples {#examples}
5282 ========
5283 
5284 Select the project files below to peruse the source code examples.
5285 
5286 🔝 [Back to table of contents](#)
5287 
5288 Source files
5289 ------------
5290 
5291 - `address.xsd` Address book schema
5292 - `address.cpp` Address book app (reads/writes address.xml file)
5293 - `addresstypemap.dat` Schema namespace prefix name preference for wsdl2h
5294 - `graph.h` Graph data binding (tree, digraph, cyclic graph)
5295 - `graph.cpp` Test graph serialization as tree, digraph, and cyclic
5296 
5297 🔝 [Back to table of contents](#)
5298 
5299 Generated files
5300 ---------------
5301 
5302 - `address.h` gSOAP-specific data binding definitions from address.xsd
5303 - `addressStub.h` C++ data binding definitions
5304 - `addressH.h` Serializers
5305 - `addressC.cpp` Serializers
5306 - `address.xml` Address book data generated by address app
5307 - `graphStub.h` C++ data binding definitions
5308 - `graphH.h` Serializers
5309 - `graphC.cpp` Serializers
5310 - `g.xsd` XSD schema with `g:Graph` complexType
5311 - `g.nsmap` xmlns bindings namespace mapping table
5312 
5313 🔝 [Back to table of contents](#)
5314 
5315 Build steps
5316 -----------
5317 
5318 Building the AddressBook example:
5319 
5320  wsdl2h -g -t addresstypemap.dat address.xsd
5321  soapcpp2 -0 -CS -I../../import -p address address.h
5322  c++ -I../.. address.cpp addressC.cpp -o address -lgsoap++
5323 
5324 Option `-g` produces bindings for global (root) elements in addition to types.
5325 In this case the root element `a:address-book` is bound to `_a__address_book`.
5326 The complexType `a:address` is bound to class `a__address`, which is also the
5327 type of `_a__address_book`. This option is not required, but allows you to use
5328 global element tag names when referring to their serializers, instead of their
5329 type name. Option `-0` removes the SOAP protocol. Options `-C` and `-S`
5330 removes client and server code generation. Option `-p` renames the output
5331 `soap` files to `address` files.
5332 
5333 See the `address.cpp` implementation and [related pages](pages.html).
5334 
5335 The `addresstypemap.dat` file specifies the XML namespace prefix for the
5336 bindings:
5337 
5338  # Bind the address book schema namespace to prefix 'a'
5339 
5340  a = "urn:address-book-example"
5341 
5342  # By default the xsd:dateTime schema type is translated to time_t
5343  # To map xsd:dateTime to struct tm, enable the following line:
5344 
5345  # xsd__dateTime = #import "../../custom/struct_tm.h"
5346 
5347  # ... and compile/link with custom/struct_tm.c
5348 
5349 The DOB field is a `xsd:dateTime`, which is bound to `time_t` by default. To
5350 change this to `struct tm`, enable the import of the `xsd__dateTime` custom
5351 serializer by uncommenting the definition of `xsd__dateTime` in
5352 `addresstypemap.dat`. Then change `soap_dateTime2s` to `soap_xsd__dateTime2s`
5353 in the code.
5354 
5355 Building the graph serialization example:
5356 
5357  soapcpp2 -CS -I../../import -p graph graph.h
5358  c++ -I../.. graph.cpp graphC.cpp -o graph -lgsoap++
5359 
5360 To compile without using the `libgsoap++` library: simply compile
5361 `stdsoap2.cpp` together with the above.
5362 
5363 🔝 [Back to table of contents](#)
5364 
5365 Usage
5366 -----
5367 
5368 To execute the AddressBook example:
5369 
5370  ./address
5371 
5372 To execute the Graph serialization example:
5373 
5374  ./graph
5375