GSOAP

History

The gSOAP toolkit started as a research project at the Florida State University by Prof. Robert van Engelen in 1999. The project introduced new methods for highly-efficient XML parsing (pull parsing) and serialization of C/C++ data directly in XML and later also in SOAP. The project also succeeded at defining type-safe data bindings between XML schema types and a wide variety of C/C++ data types. The toolkit uses automatic programming to simplify the development and invocation of Web services using efficient auto-generated XML serializers to send and receive C/C++ data directly. A domain-specific C compiler tool generates source code that efficiently converts native C data structures to XML and back. The toolkit was further developed to support the SOAP web services messaging protocol, introduced at around the same time, therefore the name "gSOAP" (generic XML and SOAP). Further development took place under ownership of Genivia Inc.. This includes the addition of new WSDL and XML schema processing capabilities in 2003 as well as the addition of many WS-* web services protocol capabilities, XML-RPC messaging, support for the JSON data format, and a stand-alone web server. The gSOAP toolkit is written in portable C/C++ and uses a form of bootstrapping by generating its own code to implement a converter to translate WSDL/XSD specifications to C/C++ source code for WSDL/XSD meta-data bindings. The gSOAP software is licensed under the GPLv2 open source license and commercial-use source code licenses.

Web Service Operations by Example

An example web service operation in C for retrieving the lodging rate of a hotel given a number of guests can be declared in annotated form as

The last parameter of the function is always the service return value, which can be denoted as void for one-way operations and should be a struct/class to bundle multiple service return parameters. The function's int return value is used for error diagnostics.

A service invocation in C using the auto-generated soap_call_ns__get_rate function is executed as follows:

To facilitate web services implementations for legacy C and C++ systems, the prefix qualification of identifier names in C/C++ can be omitted or can be replaced by colon notation, for example ns:get_rate rather than ns__get_rate. The punctuation is removed in the auto-generated source code that is used in project builds.

A service invocation in C++ using the auto-generated Proxy class is executed as follows (using the Proxy's default endpoint URL and SOAP action values):

By using annotations and identifier naming conventions, i.e. qualification with the prefix ns__ for the function ns__get_rate and by declaring properties of the ns namespace using the //gsoap directives in the example, a binding is established to web service operations. The auto-generated Web Services Description Language (WSDL) document declares a request message, a response message, and the get-rate operation portType interface and SOAP binding for the ns__get_rate function as follows:

where the request and responses messages of the operation refer to XML elements that are defined in the types section of the WSDL as follows:

Likewise, client and server C/C++ source code can be auto-generated from a set of WSDLs and XML schemas. Services must be completed by defining the appropriate service operations. For example, the auto-generated C++ service class for this WSDL must be completed by defining the get_rate method as follows:

There are no restrictions on the type of the operation parameters that can be marshaled in XML for web service messaging, except that certain type declaration conventions and annotations should be followed to establish a data binding.

Data Binding by Example

To establish an XML data binding with C/C++ data types, gSOAP uses three basic forms of source code annotation: directives, identifier naming conventions, and punctuation.

A fully annotated structure declaration in C for a hierarchical employee record may appear as

where the following annotations and conventions are used:

The gSOAP tools convert C/C++ data types to/from XML schema data types. Since C does not support namespaces and struct/class member names cannot be namespace-qualified in C++, the use of identifier naming conventions in gSOAP allow for binding this structure and its members to an XML schema complexType that is auto-generated as follows:

Furthermore, unions in a struct/class that are annotated with a special selector field for union member selection are mapped to/from schema choice particles, STL containers are mapped to/from sequence particles, enumerations are mapped to/from XML schema simpleType enumerations, and standard C/C++ primitive types are mapped to/from XSD types. For conversion of XSD schema to C/C++ data types, the actual mapping is configurable in gSOAP with a type mapping file.

An instance of the example hierarchical employee structure is serialized in XML as a tree by default, for example

When the SOAP encoding style is enabled, the XML serialization in gSOAP respects co-referenced objects and cyclic data structures as per SOAP encoding rules resulting in XML with id-ref edges.

Features