C and C++ XML Data Bindings

Table of Contents

• Introduction
• Notational Conventions
• Mapping WSDL and XML schemas to C/C++
• Using typemap.dat to customize data bindings
  • XML namespace bindings
  • XSD type bindings
  • Custom serializers for XSD types
    • xsd:integer
    • xsd:decimal
    • xsd:dateTime
    • xsd:date
    • xsd:time
    • xsd:duration
  • Custom Qt serializers for XSD types
    • xsd:string
    • xsd:base64Binary
    • xsd:hexBinary
    • xsd:dateTime
    • xsd:date
    • xsd:time
  • Class/struct member additions
  • Replacing XSD types by equivalent alternatives
  • The special variables $CONTAINER, $POINTER, $SIZE and $OPTIONAL
  • User-defined content
• Mapping C/C++ to XML schema
  • Overview of serializable C/C++ types
  • Colon notation versus name prefixing with XML tag name translation
  • C++ bool and C alternative
  • Enumerations and bitmasks
  • Numerical types
  • String types
  • Date and time types
  • Time duration types
  • Classes and structs
    • Serializable versus transient types and data members
    • Derived types in C++
    • Derived types in C
    • Volatile classes and structs
    • Mutable classes and structs
    • Default and fixed member values
    • Attribute members
    • Backtick XML tags
    • Qualified and unqualified members
    • Defining document root elements
    • (Smart) pointer members and their occurrence constraints
    • Container and array members and their occurrence constraints
    • Sequencing with hidden members
    • Tagged union members
    • Tagged void pointer members
    • Adding get and set methods
    • Operations on classes and structs
  • Special classes and structs
    • SOAP-encoded arrays
    • XSD hexBinary and base64Binary types
    • DIME/MIME/MTOM attachment binary types
    • Wrapper class/struct with simpleContent
    • DOM anyType and anyAttribute
• Directives
  • Service directives
  • Service method directives
  • Schema directives
  • Schema type directives
• Serialization rules
  • SOAP document versus rpc style
  • SOAP literal versus encoding
  • SOAP 1.1 versus SOAP 1.2
  • XML serialization
• Input and output
  • Reading and writing from/to files and streams
  • Reading and writing from/to string buffers
• Memory management
  • Memory management in C
  • Memory management in C++
• Context flags to initialize the soap struct
• Context parameter settings
• Error handling and reporting
• Features and limitations
• Removing SOAP namespaces from XML payloads
• Examples

Introduction

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 a 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 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, participating in the development and testing of the W3C XML Schema Patterns for Databinding Interoperability, and continues by contributing to the development of OASIS open standards in partnership with leading IT companies in the world.

🔝 Back to table of contents

Notational Conventions

The typographical conventions used by this document are:

• Courier denotes C and C++ source code.
• Courier denotes XML content, JSON content, file and path names, and URIs.
• Courier 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++

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 .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 -c) and saves the data binding interface to a interface header file file.h that uses familiar C/C++ syntax extended with //gsoap 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