The gSOAP Toolkit for SOAP and REST Web Services and XML-Based Applications

The gSOAP toolkit is a C and C++ software development toolkit for SOAP and REST XML Web services and generic C/C++ XML data bindings. The toolkit analyzes WSDLs and XML schemas (separately or as a combined set) and maps the XML schema types and the SOAP/REST XML messaging protocols to easy-to-use and efficient C and C++ code. It also supports exposing (legacy) C and C++ applications as XML Web services by auto-generating XML serialization code and WSDL specifications. Or you can simply use it to automatically convert XML to/from C and C++ data. The toolkit supports options to generate pure ANSI C or C++ with or without STL.

The gSOAP toolkit is used by most of the top Fortune 500 companies and all of the top 15 technology companies. Speed, reliability and flexibility, coupled with a proven track record and used by some of the largest technology vendors makes it an ideal platform to develop applications using Web services and XML processing. Applications include embedded systems, mobile devices, telecommunications, routers, online games, Web TV, banking systems, auction systems, news outlets, network management systems, grid and cloud computing platforms, and security software. See for example success stories.

The gSOAP toolkit offers a comprehensive and transparent C/C++ XML data binding solution through autocoding techniques. This saves developers substantial time to implement XML Web services in C/C++. In addition, the use of XML data bindings significantly simplifies the use of XML in applications by automatically mapping XML to C/C++ data types. Application developers no longer need to adjust the application logic to specific libraries and XML-centric data representations such as DOM.

The toolkit is compliant with WS-I Basic Profile 1.0a, 1.1, and 1.2, passed W3C Databinding interoperability testing, and interoperates with other SOAP/REST stacks such as WCF, .NET, and Axis. Highlights are support for addressing and security protocols, streaming attachments (MTOM, MIME, DIME) for efficient binary transfers. Transfer over HTTP(S), TCP/UDP, and other transport protocols is supported using convenient plugins (or user-defined callbacks in case you want to override the I/O).

The gSOAP toolkit implements an ANSI C and C++ XML data binding through the use of compiler technologies. These technologies map XML schemas to C/C++ definitions and vice versa. There are two main advantages to this approach. Firstly, strong typing ensures safe use of typed data in your application and also guarantees that the XML data has passed XML parsing validation. Secondly, compiler-based schema-specific parsing and validation is more efficient than most other XML parsing techniques.

The gSOAP toolkit also consumes and generates WSDL and XML schemas (XSD). It maps existing C/C++ data types and application functions to WSDL, thereby supporting and simplifying the conversion of legacy code into Web services. Code portability has been achieved for many platforms, including embedded systems and real-time software.

Getting Started: a quick how-to tutorial on gSOAP. Another older how-to start with gSOAP.

Fact Sheet: a quick overview of key features.

Licensing: open source licensing model (GPLv2) and commercial-use source code licenses available.

Download: get started today.

Why use gSOAP?

Here is a summary of 16 reasons why we believe you may want to try gSOAP for your projects:
  1. Portability: gSOAP supports most platforms, including embedded systems and small OS (for example WinCE, Symbian, and PalmOS). Portability is tested for Windows (98, XP, Vista), Linux, Unix, Mac OS X, Solaris, HP-UX, AIX, FreeBSD, TRU64, Irix, QNX, and VxWorks.
  2. Stability: the software is mature. Development and testing took place over several years since 2001. The software is used by many industrial projects and products.
  3. Broad user base: over 250,000 downloads since 2003, over 6,000 mailing list members, and thousands of license/support agreements with companies, including several Fortune 100 companies. Here is a brief selection of the success stories and a summary of user testimonials.
  4. All-in-one package: independence from third-party tools and libraries ensures successful builds and reliable runtime execution.
  5. Open source: free open source for non-commercial use (GPLv2). Commercial-use licensing available.
  6. C and C++ support: supports both pure ANSI C and mixed C/C++ application development.
  7. Comprehensive XML data bindings: the gSOAP toolkit implements a pure and native C/C++ data binding to XML using automatic mappings and code generation for user-defined C and C++ data types. The toolkit automatically serializes pointer-based data structures, including cyclic graphs, and supports STL (partly), unions, enums, and class inheritance. Try the online demo (requires URL of WSDL or XSD).
  8. Interoperability and Compliance: the toolkit follows the WS-I Basic Profile 1.0a, 1.1, and 1.2 compliance recommendations. It warns about potential interoperability issues before building a new Web service application, so you don't have to go through another development cycle to make your services compliant. In addition, a report is available to check compliance. In addition, the W3C Databinding Interoperability Results for gSOAP show exceptionally good XML-to-type mappings (true XML-to-type mappings, not XML to DOM-like structures).
  9. Industry-standard protocols: SOAP 1.1/1.2 (RPC encoding and document/literal styles), WSDL 1.1/2.0, and UDDI v2. WS-Policy 1.2/1.5, WS-SecurityPolicy 1.2, WS-ReliableMessaging, WS-Addressing. Supports XML schema primitive XSD types, simpleTypes, complexTypes, extension, restriction, elements, attributes, element/attribute references, sequence/all/choice, groups, attributeGroups, substitutions, any/anyAttribute, schema import/include/redefine, and SOAP arrays (including polymorphic and multi-dimensional sparse arrays).
  10. Transport: HTTP/S, TCP, UDP (SOAP-over-UDP), MIME (SwA), DIME (streaming), MTOM (streaming), HTTP1.0/1.1, IPv4, IPv6, RSS, XML-RPC, WS-Addressing. HTTP stack supports HTTP/1.1 POST/GET SOAP/XML messaging with compression, chunking, keep-alive, logging, and SSL encryption.
  11. Security: HTTPS and WS-Security: authentication, tokens, digital signatures.
  12. Speed: the schema-specific compiler-generated code is fast. Benchmarking shows speeds comparable or better than fastest XML parsers (reported by peer-reviewed technical papers). Typical round-trip SOAP service invocation latencies are well below 1ms.
  13. Debugging and Testing: in debug mode generates transport and activity logs, also in debug mode the automatic memory management warns about leaks, the tools generate sample XML messages (from WSDL) for on- and off-line testing, automatic generation of echo test server code for client testing.
  14. Small footprint: client applications can be under 100K with a total runtime memory footprint of under 150K. Memory management uses garbage collection so (deserialized) data can be cleaned up without a hassle.
  15. Numerous examples: the software package includes many code examples, including stand-alone HTTP/1.1 and HTTPS-secure Web Server.
  16. Web server integration: includes Apache_mod, IIS, WinInet, CGI, and FastCGI interfaces to integrate your services.
  17. Active maintenance and development: the software is feature rich, but there are always new features to be desired. See the latest news on current developments and future plans.

What are the gSOAP tools?

Download the latest gSOAP package from the SourceForge gSOAP project site. The gSOAP distribution package includes two compiler tools to develop your applications: The 'wsdl2h' parser converts WSDL into gSOAP header file specifications of Web services. This specification gives a C/C++ transparent view of the server's functionality. The header file is processed by 'soapcpp2' to generate the source code stubs and skeletons to invoke the service or build a new service based on the WSDL.

The next section explains how these tools are used to build client and server applications.

A Quick How-To

This document is also available in Belarusian.

We use the gSOAP 'wsdl2h' WSDL parser to obtain the gSOAP header file specification of a Web service from a WSDL document.

To obtain a header file from a WSDL document, run 'wsdl2h' on a WSDL:
wsdl2h -o outfile.h infile.wsdl

where infile.wsdl can be a resident WSDL file or a Web location of the WSDL. The outfile.h is the generated output file. For example:
wsdl2h -o XMethodsQuery.h

This generates the header file XMethodsQuery.h. The header file defines the service in a more familiar C/C++ header format that you can browse within your IDE (or with Doxygen).

Next, we run the gSOAP compiler 'soapcpp2' on the gSOAP header file to produce the source code to implement the client application. The 'soapcpp2' stub and skeleton compiler generates proxies (and RPC stubs) for your client application, as illustrated below.

The gSOAP runtime library provides a transport layer with an HTTP stack on top of TCP/IP as well as secure SSL and DIME/MIME attachment support.

To develop a service application, run the gSOAP 'wsdl2h' parser on a WSDL to create a gSOAP header file. The header file is compiled with the 'soapcpp2' compiler:

The 'soapcpp2' compiler generates the C/C++ Web service skeletons. You can also take a legacy C/C++ application and develop a service simply by entering the C/C++ Web service method operations and data types into a header file. The 'soapcpp2' compiler generates the source code for your project and produces a WSDL to advertize your Web service.

Example Client

The XMethods Delayed Stock Quote Web Service provides a delayed stock quote for a given ticker name, see XMethods Delayed Stock Quote for details. The WSDL description of the Delayed Stock Quote Web Service provides the following details:
Endpoint URL:
SOAP action:  "" (2 quotes) 
Remote method namespace:  urn:xmethods-delayed-quotes
Remote method name:  getQuote
   Input parameter:  symbol of type xsd:string
   Output parameter:  Result of type xsd:float

The gSOAP 'wsdl2h' WSDL parser tool converts the WSDL:
wsdl2h -c -o quote.h

The -c options ensures that the client application can be developed in pure C. The generated quote.h file contains:
//gsoap ns1 service name: net_DOTxmethods_DOTservices_DOTstockquote_DOTStockQuoteBinding
//gsoap ns1 service type: net_DOTxmethods_DOTservices_DOTstockquote_DOTStockQuotePortType
//gsoap ns1 service port:
//gsoap ns1 service namespace: urn:xmethods-delayed-quotes
//gsoap ns1 service documentation: Definitions generated by the gSOAP WSDL parser 1.0
// Service : web service
//gsoap ns1 service method-style: getQuote rpc
//gsoap ns1 service method-encoding: getQuote
//gsoap ns1 service method-action: getQuote urn:xmethods-delayed-quotes#getQuote
int ns1__getQuote(char *symbol, float &Result);

(Note: the contents may vary depending on the 'wsdl2h' release.)

Because the name of the service is a bit lengthy, we rename it in the header file into something simpler for sake of convenience:
//gsoap ns1 service name: Quote

The service method is declared as a ns1__getQuote function prototype which specifies all of the necessary details for the gSOAP stub and skeleton compiler 'soapcpp2' to generate the stub routine and parameter marshalling code for a client application to interact with the Delayed Stock Quote service.

The gSOAP stub and skeleton compiler is invoked on this quote.h header file from within an IDE (e.g. MSVC++ or Borland C++), from a makefile, or from the command line with:
soapcpp2 -c quote.h

The -c option ensures that the generated code is pure C.

The following function is generated by the gSOAP compiler:
int soap_call_ns1__getQuote(struct soap *soap, char *URL, char *action, char *symbol, float &Result);

Note that the parameters of the generated soap_call_ns1__getQuote proxy are identical to the ns1__getQuote function prototype with three additional input parameters: soap is a run-time gSOAP environment, URL is the SOAP Web service endpoint URL passed as a string which must be NULL to use the endpoint specified in the WSDL and action is a string that should denote the SOAP action required by the Web service, which must be NULL to use the SOAPAction specified in the WSDL. The use of the prefix ns1__ in the remote method name in the function prototype declaration serves as a namespace prefix for the remote method. A namespace prefix is distinghuished from the function name by a pair of underscores as in ns1__getQuote.

The following C client program invokes the proxy to retrieve the latest IBM stock quote from the XMethods Delayed Stock Quote service:
#include "soapH.h" // obtain the generated stub 
#include "Quote.nsmap" // obtain the generated XML namespace mapping table for the Quote service 

   struct soap *soap = soap_new();
   float quote; 
   if (soap_call_ns1__getQuote(soap, NULL, NULL, "IBM", quote) == SOAP_OK) 
      printf("Current IBM Stock Quote = %g\n", quote);
   else // an error occurred 
      soap_print_fault(soap, stderr); // display the SOAP fault on the stderr stream 

A C++ client application can use the generated proxy class, as shown in this example:
#include "soapQuoteProxy.h" // get proxy
#include "Quote.nsmap" // get namespace bindings
int main()
   Quote q;
   float r;
   if (q.ns1__getQuote("IBM", r) == SOAP_OK)
      std::cout << r << std::endl;
      soap_print_fault(q.soap, stderr);
   return 0;

This assumes that the code was produced by omitting the -c option for 'wsdl2h' and 'soapcpp2'.

Example Web Service

Use the gSOAP 'wsdl2h' WSDL parser to create a header file for a service you want to develop, or you can write your own header file specifications to develop a new Web service. The latter approach is useful when you don't have a WSDL to start with and you don't want to bother with the details of the WSDL specification. The following example specifies a new SOAP Web calculator service in a header file. We don't use the WSDL parser to create a service, because we can define the service in a header file and let the gSOAP 'soapcpp2' compiler generate a WSDL for us instead. We want to develop a service that implements three remote methods using SOAP RPC encoding (note: doc/lit is the default):
// Contents of file "calc.h": 
//gsoap ns service name: calculator
//gsoap ns service style: rpc
//gsoap ns service encoding: encoded
//gsoap ns service port: http://mydomain/path/calculator.cgi
//gsoap ns service namespace: urn:calculator
int ns__add(double a, double b, double &result); 
int ns__sub(double a, double b, double &result); 
int ns__sqrt(double a, double &result); 

The add and sub methods are intended to add and subtract two double floating point numbers stored in input parameters a and b and return the result of the operation in the result output parameter. The sqrt method is intended to take the square root of input parameter a and to return the result in the output parameter result.

The gSOAP stub and skeleton compiler is invoked on this calc.h header file from within an IDE (e.g. MSVC++ or Borland C++), from a makefile, or from the command line with:
soapcpp2 calc.h

The compiler generates the skeleton routines and a WSDL description of the service. Here is an example Calculator service application that uses the generated skeletons. The soap_serve routine handles client requests:
// Contents of file "calc.cpp": 
#include "soapH.h" 
#include "calculator.nsmap" 
#include <math.h> 

   soap_serve(soap_new()); // call the incoming remote method request dispatcher 

// Implementation of the "add" remote method: 
int ns__add(struct soap *soap, double a, double b, double &result) 

   result = a + b; 
   return SOAP_OK; 

// Implementation of the "sub" remote method: 
int ns__sub(struct soap *soap, double a, double b, double &result) 

   result = a - b; 
   return SOAP_OK; 

// Implementation of the "sqrt" remote method: 
int ns__sqrt(struct soap *soap, double a, double &result) 

   if (a >= 0) 
      result = sqrt(a); 
      return SOAP_OK; 
      return soap_sender_fault(soap, "Square root of negative value", "I can only compute the square root of a non-negative value");

The implementation of the remote methods return a SOAP status code. The code SOAP_OK denotes success, while soap_sender_fault returns an exception. This application is intended to run as a CGI application at the specified location (http://mydomain/path/calculator.cgi). However, you can build a stand-alone HTTP/HTTPS Web server that serves regular dynamic HTML content and SOAP/XML Web services, see the gSOAP Web Server (screen shot). You can also use Apache_mod, WinInet, IIS, or Fast CGI. Apache, WinInet, and IIS are recommended over stand-alone services and provide load balancing, access control, tracing, and more.

Citing gSOAP: Publications

When citing the gSOAP project, please cite the following paper that first introduced gSOAP: Other gSOAP and Web services-related publications: