gsoap 2.8.82

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