• Source: GSOAP

gSOAP is a C and C++ software development toolkit for SOAP/XML web services and generic XML data bindings. Given a set of C/C++ type declarations, the compiler-based gSOAP tools generate serialization routines in source code for efficient XML serialization of the specified C and C++ data structures. Serialization takes zero-copy overhead.




History


The gSOAP toolkit started as a research project at the Florida State University by professor 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 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 compiler-based tool generates source code that efficiently converts native C/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) and to use the approach for scientific data exchange. Further development and maintenance of the software took place under ownership of Genivia Inc. This includes the addition of new WSDL and XML Schema processing capabilities as well as the addition of many WS-* web services protocol capabilities such as WS-Security optimizations, XML-RPC messaging, support for the JSON data format, plugin modules to integrate gSOAP in Apache and IIS web servers, and third-party plugins such as for Grid Services. 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. The gSOAP software is widely used in industrial projects and mission-critical infrastructures.




XML 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.




XML 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:

namespace qualification of types and members by identifier naming conventions: ns__employee_record, xml__lang
attributes for members: @char*, @int
default values for members: xml__lang = "en", ID = 9999
occurrence constraints in the form of minOccurs:maxOccurs for XML validation: full_name 1:1, size 0:12
dynamic arrays of element sequences consist of a pair of a special size field and an array pointer member: $int size; struct ns__employee_record *manages
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.
The auto-generated XML data binding includes read and write operations to/from a file, string or stream. For example, an ns__employee_record object has read and write operations:

To read an employee record from an XML file:

Parsed XML is internally validated against the data bindings' constraints.




XML REST API


Application data can be sent and received to/from a REST XML service. The XML data binding provides REST XML API calls. For example, given the ns__employee_record XML data binding of the previous section, the following GET, PUT and POST operations are auto-generated:

The POST functions should be called together, first a POST_send to transmit XML data to the endpoint URL followed by a POST_recv to accept the response data (may be of a different type).
Received XML is internally validated against the data bindings' constraints.




Features


XML data binding for C and C++ based on automatic programming with source-to-source code generation
Customizable client/server source code auto-generation in ANSI C and ISO C++
Integrated high-speed, schema-specific XML pull parsing with XML validation
Web Services Description Language (WSDL) 1.1 and 2.0
Web services SOAP 1.1 and 1.2
Streaming Message Transmission Optimization Mechanism (MTOM) and DIME/MIME attachments
Representational state transfer (REST) HTTP(S) 1.0/1.1
Verified WS-I Basic Profile 1.0a, 1.1, and 1.2 compliant
Verified W3C schema patterns for data binding, full test pattern coverage
XML-RPC for C and C++
JSON for C and C++
RSS 0.91, 0.92, 2.0
WS-Security
WS-Policy 1.2, 1.5 and WS-SecurityPolicy 1.2
WS-Addressing 2003/03, 2004/03, 2005/03
WS-ReliableMessaging 1.0 and 1.1
WS-Discovery 1.0/1.1
SOAP-over-UDP
Universal Description Discovery and Integration (UDDI) v2 API
HTTP basic and digest authentication, NTLM authentication, proxy authentication
IPv4 and IPv6 with SSL/TLS with SSL session caching (based on OpenSSL or GNUTLS)
XML compression with gzip
Apache 1.x and 2.0 modules, IIS ISAPI and WinInet modules, CGI and FastCGI
Stand-alone web server support (multithreaded, pooling)
Integrated memory management with deallocation and leak detection
Architecture with plug-ins for additional capabilities
Internationalization/localization support (UTF8, UCS4, MB encodings, etc.)
Platform neutral, supports small devices (Symbian, VxWorks, Android, iPhone)




References






See also


Getting started with gSOAP
project page on SourceForge
XML data binding
Serialization
List of web service frameworks
List of web service specifications

Kata Kunci Pencarian:

• Mozilla Public License
• GSOAP
• WS-I Basic Profile
• XML
• Serialization
• WS-ReliableMessaging
• 3G Bridge
• Comparison of code generation tools
• List of web service frameworks
• XML data binding
• Devices Profile for Web Services