GSOAP

Last updated
gSOAP
Developer(s) Robert van Engelen
Initial releaseDecember 8, 2000;22 years ago (2000-12-08)
Stable release
2.8.131 / September 23, 2023 (2023-09-23)
Repository
Written in C and C++
Operating system Cross-platform
Type Web development software
License GPL v2, commercial licensing
Website https://www.genivia.com/dev.html
https://sourceforge.net/projects/gsoap2/

gSOAP [1] [2] 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.

Contents

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 [2] for highly-efficient XML parsing (pull parsing) [3] [4] and serialization of C/C++ data directly in XML and later also in SOAP. The project succeeded [5] 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. [1] 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. [6] 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, [7] 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. [8] [9] 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 [10] 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

//gsoap ns service namespace: tempuri//gsoap ns service style:     document//gsoap ns service encoding:  literalintns__get_rate(char*hotel,intguests,float*rate);

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:

constchar*URL="http://www.example.com/hotels";constchar*action=NULL;structsoap*ctx=soap_new();// new contextfloatrate;interr=soap_call_ns__get_rate(ctx,URL,action,"Happy Inn",2,&rate);if(err==SOAP_OK&&rate<100.00)lets_go();soap_end(ctx);// deallocate deserialized datasoap_free(ctx);// deallocate context

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

Proxyproxy;floatrate;interr=proxy.get_rate("Happy Inn",2,&rate);if(err==SOAP_OK&&rate<100.00)lets_go();proxy.destroy();// deallocate deserialized data

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:

<definitionsname="Service"targetNamespace="tempuri"xmlns:tns="tempuri"xmlns:ns="tempuri"xmlns="http://schemas.xmlsoap.org/wsdl/"> ... <messagename="get-rateRequest"><partname="parameters"element="ns:get-rate"/></message><messagename="get-rateResponse"><partname="parameters"element="ns:get-rateResponse"/></message><portTypename="ServicePortType"><operationname="get-rate"><inputmessage="tns:get-rateRequest"/><outputmessage="tns:get-rateResponse"/></operation></portType><bindingname="Service"type="tns:ServicePortType"><SOAP:bindingstyle="document"transport="http://schemas.xmlsoap.org/soap/http"/><operationname="get-rate"><SOAP:operationsoapAction=""/><input><SOAP:bodyparts="parameters"use="literal"/></input><output><SOAP:bodyparts="parameters"use="literal"/></output></operation></binding>

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:

<types><schematargetNamespace="tempuri"...><elementname="get-rate"><complexType><sequence><elementname="hotel"type="xsd:string"minOccurs="0"maxOccurs="1"nillable="true"/><elementname="guests"type="xsd:int"minOccurs="1"maxOccurs="1"/></sequence></complexType></element><elementname="get-rateResponse"><complexType><sequence><elementname="rate"type="xsd:float"minOccurs="0"maxOccurs="1"nillable="true"/></sequence></complexType></element></schema></types>

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:

intService::get_rate(char*hotel,intguests,float*rate){*rate=...// determine the lodging rate of the hotel given the number of guestsreturnSOAP_OK;}

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

//gsoap ns schema namespace: tempuri//gsoap ns schema form:      qualifiedstructns__employee_record{@char*xml__lang="en";@intID=9999;char*full_name1:1;$intsize0:12;structns__employee_record*manages;};

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:

<schematargetNamespace="tempuri"xmlns:ns="tempuri"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns="http://www.w3.org/2001/XMLSchema"elementFormDefault="qualified"attributeFormDefault="qualified"><complexTypename="employee-record"><sequence><elementname="full-name"type="xsd:string"minOccurs="1"maxOccurs="1"nillable="true"/><elementname="manages"type="ns:employee-record"minOccurs="0"maxOccurs="12"/></sequence><attributeref="xml:lang"use="default"default="en"/><attributename="ID"type="xsd:int"use="default"default="9999"/></complexType></schema>

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

<ns:employeexmlns:ns="tempuri"xml:lang="en"ns:ID="12"><ns:full-name>JaneDoe</ns:full-name><ns:managesxml:lang="en"ns:ID="34"><ns:full-name>JohnDoe</ns:full-name></ns:manages><ns:managesxml:lang="en"ns:ID="56"><ns:full-name>BobOz</ns:full-name><ns:managesxml:lang="en"ns:ID="78"><ns:full-name>AliceOz</ns:full-name></ns:manages></ns:manages></ns:employee>

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:

intsoap_read_ns__employee_record(structsoap*,ns__employee_record*);intsoap_write_ns__employee_record(structsoap*,constns__employee_record*);

To read an employee record from an XML file:

structsoap*ctx=soap_new();ctx->recvfd=open("employee.xml",O_RDONLY);if(ctx->recvfd){ns__employee_recordemployee;if(soap_read_ns__employee_record(ctx,&employee)==SOAP_OK)...close(ctx->recvfd);}soap_end(ctx);soap_destroy(ctx);// also deletes employee datasoap_free(ctx);

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:

intsoap_GET_ns__employee_record(structsoap*,constchar*URL,ns__employee_record*);intsoap_PUT_ns__employee_record(structsoap*,constchar*URL,constns__employee_record*);intsoap_POST_send_ns__employee_record(structsoap*,constchar*URL,constns__employee_record*);intsoap_POST_recv_ns__employee_record(structsoap*,ns__employee_record*);

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

Related Research Articles

In computing, a namespace is a set of signs (names) that are used to identify and refer to objects of various kinds. A namespace ensures that all of a given set of objects have unique names so that they can be easily identified.

<span class="mw-page-title-main">SOAP</span> Messaging protocol for web services

SOAP is a messaging protocol specification for exchanging structured information in the implementation of web services in computer networks. It uses XML Information Set for its message format, and relies on application layer protocols, most often Hypertext Transfer Protocol (HTTP), although some legacy systems communicate over Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission.

<span class="mw-page-title-main">XML</span> Markup language by the W3C for encoding of data

Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing arbitrary data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. The World Wide Web Consortium's XML 1.0 Specification of 1998 and several other related specifications—all of them free open standards—define XML.

XSD, a recommendation of the World Wide Web Consortium (W3C), specifies how to formally describe the elements in an Extensible Markup Language (XML) document. It can be used by programmers to verify each piece of item content in a document, to assure it adheres to the description of the element it is placed in.

In computing, RELAX NG is a schema language for XML—a RELAX NG schema specifies a pattern for the structure and content of an XML document. A RELAX NG schema is itself an XML document but RELAX NG also offers a popular compact, non-XML syntax. Compared to other XML schema languages RELAX NG is considered relatively simple.

Extensible Application Markup Language is a declarative XML-based language developed by Microsoft for initializing structured values and objects. It is available under Microsoft's Open Specification Promise.

Jakarta XML Binding is a software framework that allows Java EE developers to map Java classes to XML representations. JAXB provides two main features: the ability to marshal Java objects into XML and the inverse, i.e. to unmarshal XML back into Java objects. In other words, JAXB allows storing and retrieving data in memory in any XML format, without the need to implement a specific set of XML loading and saving routines for the program's class structure. It is similar to xsd.exe and XmlSerializer in the .NET Framework.

An XML schema is a description of a type of XML document, typically expressed in terms of constraints on the structure and content of documents of that type, above and beyond the basic syntactical constraints imposed by XML itself. These constraints are generally expressed using some combination of grammatical rules governing the order of elements, Boolean predicates that the content must satisfy, data types governing the content of elements and attributes, and more specialized rules such as uniqueness and referential integrity constraints.

<span class="mw-page-title-main">XBRL</span> Exchange format for business information

XBRL is a freely available and global framework for exchanging business information. XBRL allows the expression of semantic meaning commonly required in business reporting. The standard was originally based on XML, but now additionally supports reports in JSON and CSV formats, as well as the original XML-based syntax. XBRL is also increasingly used in its Inline XBRL variant, which embeds XBRL tags into an HTML document. One common use of XBRL is the exchange of financial information, such as in a company's annual financial report. The XBRL standard is developed and published by XBRL International, Inc. (XII).

XMLBeans is a Java-to-XML binding framework which is part of the Apache Software Foundation XML project.

Catalogue Service for the Web (CSW), sometimes seen as Catalogue Service - Web, is a standard for exposing a catalogue of geospatial records in XML on the Internet. The catalogue is made up of records that describe geospatial data, geospatial services, and related resources.

<span class="mw-page-title-main">RDFLib</span> Python library to serialize, parse and process RDF data

RDFLib is a Python library for working with RDF, a simple yet powerful language for representing information. This library contains parsers/serializers for almost all of the known RDF serializations, such as RDF/XML, Turtle, N-Triples, & JSON-LD, many of which are now supported in their updated form. The library also contains both in-memory and persistent Graph back-ends for storing RDF information and numerous convenience functions for declaring graph namespaces, lodging SPARQL queries and so on. It is in continuous development with the most recent stable release, rdflib 6.1.1 having been released on 20 December 2021. It was originally created by Daniel Krech with the first release in November, 2002.

The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services. WADL models the resources provided by a service and the relationships between them. WADL is intended to simplify the reuse of web services that are based on the existing HTTP architecture of the Web. It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser. WADL was submitted to the World Wide Web Consortium by Sun Microsystems on 31 August 2009, but the consortium has no current plans to standardize it. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL), which can also be used to describe REST web services.

The Pronunciation Lexicon Specification (PLS) is a W3C Recommendation, which is designed to enable interoperable specification of pronunciation information for both speech recognition and speech synthesis engines within voice browsing applications. The language is intended to be easy to use by developers while supporting the accurate specification of pronunciation information for international use.

WS-Security Policy is a web services specification, created by IBM and 12 co-authors, that has become an OASIS standard as of version 1.2. It extends the fundamental security protocols specified by the WS-Security, WS-Trust and WS-Secure Conversation by offering mechanisms to represent the capabilities and requirements of web services as policies. Security policy assertions are based on the WS-Policy framework.

<span class="mw-page-title-main">Web Services Description Language</span> XML-based interface description language

The Web Services Description Language is an XML-based interface description language that is used for describing the functionality offered by a web service. The acronym is also used for any specific WSDL description of a web service, which provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns. Therefore, its purpose is roughly similar to that of a type signature in a programming language.

In computing, Open Data Protocol (OData) is an open protocol that allows the creation and consumption of queryable and interoperable REST APIs in a standard way. Microsoft initiated OData in 2007. Versions 1.0, 2.0, and 3.0 are released under the Microsoft Open Specification Promise. Version 4.0 was standardized at OASIS, with a release in March 2014. In April 2015 OASIS submitted OData v4 and OData JSON Format v4 to ISO/IEC JTC 1 for approval as an international standard. In December 2016, ISO/IEC published OData 4.0 Core as ISO/IEC 20802-1:2016 and the OData JSON Format as ISO/IEC 20802-2:2016.

XHTML+RDFa is an extended version of the XHTML markup language for supporting RDF through a collection of attributes and processing rules in the form of well-formed XML documents. XHTML+RDFa is one of the techniques used to develop Semantic Web content by embedding rich semantic markup. Version 1.1 of the language is a superset of XHTML 1.1, integrating the attributes according to RDFa Core 1.1. In other words, it is an RDFa support through XHTML Modularization.

<span class="mw-page-title-main">Business Intelligence Markup Language</span>

Business Intelligence Markup Language (BIML) is a domain-specific XML dialect for defining business intelligence (BI) assets. Biml authored BI assets can currently be used by the BIDS Helper add-on for Microsoft SQL Server Business Intelligence Development Studio (BIDS) and the Varigence Mist integrated development environment; both tools translate Biml metadata into SQL Server Integration Services (SSIS) and SQL Server Analysis Services (SSAS) assets for the Microsoft SQL Server platform. However, emitters can be created to compile Biml for any desired BI platform.

References

  1. 1 2 van Engelen, Robert (2008). "A Framework for Service-Oriented Computing with C and C++ Web Service Components". ACM Transactions on Internet Technology. 8 (3): 106–115. doi:10.1145/1361186.1361188. S2CID   10240041.
  2. 1 2 van Engelen, Robert; Gallivan, Kyle (2002). The gSOAP Toolkit for Web Services and Peer-To-Peer Computing Networks. IEEE International Symposium on Cluster Computing and the Grid. pp. 128–135.
  3. ↑ Head, Michael; Govinderaju, Madhu; Slominski, Aleksander; Liu, Pu; Abu-Ghazaleh, Nayef; van Engelen, Robert; Chiu, Kenneth (2005). Benchmarking XML Processors for Applications in Grid Web Services. IEEE/ACM Supercomputing (SC).
  4. ↑ Head, Michael; Govinderaju, Madhu; van Engelen, Robert; Zhang, Wei (2006). Benchmarking XML Processors for Applications in Grid Web Services. IEEE/ACM Supercomputing (SC).
  5. ↑ van Engelen, Robert; Govindaraju, Madhu; Zhang, Wei (2006). Exploring Remote Object Coherence in XML Web Services. International Conference on Web Services (ICWS). pp. 249–256.
  6. ↑ van Engelen, Robert (2003). Pushing the SOAP Envelope with Web Services for Scientific Computing. Conference on Web Services (ICWS). pp. 346–354.
  7. ↑ Robert, van Engelen; Zhang, Wei (2008). An Overview and Evaluation of Web Services Security Performance Optimizations. IEEE International Conference on Web Services (ICWS). pp. 137–144.
  8. ↑ Aloisio, Giovanni; Cafaro, Massimo; Epicoco, Italo; Lezzi, Daniele; van Engelen, Robert (2005). The GSI plug-in for gSOAP: Enhanced Security, Performance, and Reliability. International Conference on Information Technology (ITCC). pp. 304–309.
  9. ↑ Cafaro, Massimo; Lezzi, Daniele; Fiore, Sandro; Aloisio, Giovanni; van Engelen, Robert (2007). The GSI plug-in for gSOAP: building cross-grid interoperable secure grid services. International Conference on Parallel Processing and Applied Mathematics (PPAM) 2007, workshop on Models, Algorithms and Methodologies for Grid-enabled Computing Environment (MAMGCE), Springer Verlag LNCS Volume 4967. pp. 894–901.
  10. ↑ Challener, David; Yoder, Kent; Catherman, Ryan; Safford, David; Van Doorn, Leendert (2007). A practical guide to trusted computing. Pearson Education.

See also

This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.