C and C++ XML Data Bindings {#mainpage}
===========================
[TOC]
Introduction {#intro}
============
This article presents a detailed overview of the gSOAP XML data bindings for C
and C++. The XML data bindings for C and C++ are extensively used with gSOAP
Web services to serialize C and C++ data in XML as part of the SOAP/XML Web
services payloads. Also REST XML with gSOAP relies on XML serialization of C
and C++ data via XML data bindings.
The major advantage of XML data bindings is that your application data is
always **type safe** in C and C++ by binding XML schema types to C/C++ types.
So integers in XML are bound to C integers, strings in XML are bound to C or
C++ strings, complex types in XML are bound to C structs or C++ classes, and so
on. The structured data you create and accept will fit the data model and is
**static type safe**. In other words, by leveraging strong typing in C/C++,
your XML data meets **XML schema validation requirements** and satisfies **XML
interoperability requirements**.
In fact, gSOAP data bindings are more powerful than simply representing C/C++
data in XML. The gSOAP tools implement true and tested **structure-preserving
serialization** of C/C++ data in XML, including the serialization of cyclic
graph structures with id-ref XML attributes. The gSOAP tools also generate
routines for deep copying and deep deletion of C/C++ data structures to
simplify memory management. In addition, C/C++ structures are deserialized
into managed memory, managed by the gSOAP `soap` context.
At the end of this article two examples are given to illustrate the application
of XML data bindings. The first simple example `address.cpp` shows how to use
wsdl2h to bind an XML schema to C++. The C++ application reads and writes an
XML file into and from a C++ "address book" data structure as a simple example.
The C++ data structure is an STL vector of address objects. The second example
`graph.cpp` shows how C++ data can be accurately serialized as a tree, digraph,
and cyclic graph in XML. The digraph and cyclic graph serialization rules
implement SOAP 1.1/1.2 multi-ref encoding with id-ref attributes to link
elements through IDREF XML references, creating a an XML graph with pointers to
XML nodes that preserves the structural integrity of the serialized C++ data.
These examples demonstrate XML data bindings only for relatively simple data
structures and types. The gSOAP tools support more than just these type of
structures to serialize in XML. There are practically no limits to the
serialization of C and C++ data types in XML.
Also the support for XML schema (XSD) components is unlimited. The wsdl2h tool
maps schemas to C and C++ using built-in intuitive mapping rules, while
allowing the mappings to be customized using a `typemap.dat` file with mapping
instructions for wsdl2h.
The information in this article is applicable to gSOAP 2.8.26 and later
versions that support C++11 features. However, C++11 is not required. The
material and the examples in this article use plain C and C++, until the point
where we introduce C++11 smart pointers and scoped enumerations. While most of
the examples in this article are given in C++, the concepts also apply to C
with the exception of containers, smart pointers, classes and their methods.
None of these exceptions limit the use of the gSOAP tools for C in any way.
The data binding concepts described in this article were first envisioned in
1999 by Prof. Robert van Engelen at the Florida State University. An
implementation was created in 2000, named "stub/skeleton compiler". The first
articles on its successor version "gSOAP" appeared in 2002. The principle of
mapping XSD components to C/C++ types and vice versa is now widely adopted in
systems and programming languages, including Java web services and by C# WCF.
We continue to be committed to our goal to empower C/C++ developers with
powerful autocoding tools for XML. Our commitment started in the very early
days of SOAP by actively participating in
[SOAP interoperability testing](http://www.whitemesa.com/interop.htm),
participating in the development and testing of the
[W3C XML Schema Patterns for Databinding Interoperability](http://www.w3.org/2002/ws/databinding),
and continues by contributing to the development of
[OASIS open standards](https://www.oasis-open.org) in partnership with leading
IT companies in the world.
���� [Back to table of contents](#)
Mapping WSDL and XML schemas to C/C++ {#tocpp}
=====================================
To convert WSDL and XML schemas (XSD files) to code, we use the wsdl2h command
on the command line (or command prompt), after opening a terminal. The wsdl2h
command generates the data binding interface code that is saved to a special
gSOAP header file with extension `.h` that contains the WSDL service
declarations and the data binding interface declarations in a familiar C/C++
format:
wsdl2h [options] -o file.h ... XSD and WSDL files ...
This command converts WSDL and XSD files to C++ (or pure C with wsdl2h option
`-c`) and saves the data binding interface to a gSOAP header file `file.h` that
uses familiar C/C++ syntax extended with `//gsoap` [directives](#directives)
and annotations. Notational conventions are used in the data binding interface
to declare serializable C/C++ types and functions for Web service operations.
The WSDL 1.1/2.0, SOAP 1.1/1.2, and XSD 1.0/1.1 standards are supported by the
gSOAP tools. In addition, the most popular WS specifications are also
supported, including WS-Addressing, WS-ReliableMessaging, WS-Discovery,
WS-Security, WS-Policy, WS-SecurityPolicy, and WS-SecureConversation.
This article focusses mainly on XML data bindings. XML data bindings for C/C++
bind XML schema types to C/C++ types. So integers in XML are bound to C
integers, strings in XML are bound to C or C++ strings, complex types in XML
are bound to C structs or C++ classes, and so on.
A data binding is dual, meaning supporting a two way direction for development.
Either you start with WSDLs and/or XML schemas that are mapped to equivalent
C/C++ types, or you start with C/C++ types that are mapped to XSD types.
Either way, the end result is that you can serialize C/C++ types in XML such
that your XML is an instance of XML schema(s) and is validated against these
schema(s).
This covers all of the following standard XSD components with their optional
attributes and properties:
XSD component | attributes and properties
-------------- | -------------------------
schema | targetNamespace, version, elementFormDefault, attributeFormDefault, defaultAttributes
attribute | name, ref, type, use, default, fixed, form, targetNamespace, wsdl:arrayType
element | name, ref, type, default, fixed, form, nillable, abstract, substitutionGroup, minOccurs, maxOccurs, targetNamespace
simpleType | name
complexType | name, abstract, mixed, defaultAttributesApply
all | *n/a*
choice | minOccurs, maxOccurs
sequence | minOccurs, maxOccurs
group | name, ref, minOccurs, maxOccurs
attributeGroup | name, ref
any | minOccurs, maxOccurs
anyAttribute | *n/a*
And also the following standard XSD directives are covered:
directive | description
---------- | -----------
import | Imports a schema into the importing schema for referencing
include | Include schema component definitions into a schema
override | Override by replacing schema component definitions
redefine | Extend or restrict schema component definitions
annotation | Annotates a component
The XSD facets and their mappings to C/C++ are:
XSD facet | maps to
-------------- | -------
enumeration | `enum`
simpleContent | class/struct wrapper with `__item` member
complexContent | class/struct
list | `enum*` bitmas