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 top Fortune 100 companies world wide, including the top 5 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.

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.

Who's using gSOAP?

Adobe Systems, AOL, BEA, Boeing, Cisco Systems, CNR, eBay, Ericsson, Exxon/Mobile, HP, IBM, Intel, Microsoft, Nokia, Pfizer, Siemens, WindRiver, Xerox, and many others (whose names we are not allowed to disclose).

Recent News and Announcements on gSOAP

August 2013:

The long-awaited 2.8.16 release is here!


April 2013:

Analysis of gSOAP source code (GPL version) available on Ohloh by Black Duck.


December 2012:

Released gSOAP 2.8.12 with WSDL 2.0 support and other enhancements. An important fix is available for an OpenSSL crash in the client-side host check. The crash is caused by changes in the OpenSSL API .


August 2012:

Due to popular demand for supporting the ONVIF specifications, we are providing recommendations in the FAQ under "How do use gSOAP for the ONVIF specifications?". Also, Genivia Inc offers support services, just in case.


June 2012:

Released gSOAP 2.8.9 with iOS plugin and examples, WCF-interoperable examples, and WS-ReliableMessaging and WS-Security updates.


January 2012:

Erwin Zwart from GuruCE writes onHosting webservices on Windows Embedded Compact using gSOAP: Uploading a file. See the February 2011 entry below for more details on gSOAP on Windows CE.


October 2011:

Released 2.8.4 with WS-Discovery support, a Tandem NonStop bridge, and several other enhancements. In addition, another gSOAP package is available to support HP NonStop.


May 2011:

The gSOAP "XML-RPC-JSON" all-in-one solution allows XML-RPC to be used in combination with JSON in the gSOAP 2.8.3 release. XML-RPC data can be serialized in JSON and vice versa without additional coding. An XML-RPC update with JSON is available here for all pre-2.8.3 releases.


March 2011:

Jon Scobie put together an overview and walk-through of the gSOAP Apache module Brain dump or brain washed?.


February 2011:

Read more about hosting web services on Windows Embedded Compact devices using gSOAP on Windows CE from the experts at GuruCE.


January 2011:

The WS4D-gSOAP Web Services for devices project brings Service-Oriented Architecture (SOA) and Web services technology to the application domains of industrial automation, home entertainment, automotive systems and telecommunication systems.


January 2011:

Nokia article on gSOAP for Symbian: Using gSOAP for Web services. The article is intended for Symbian S60 device developers, but the article is really much more generic and useful to everyone.


December 2010:

SOAP NonStop Tandem support for C/C++ XML Web services is available in the form of a plugin-based bridge for gSOAP. Developers interested in this technology can contact the gSOAP developers, see here how to find us.


May 2010:

New Apache mod project: mod_wscpp for Apache web server integration of gSOAP services.


April 2010:

News for iPhone and iPad developers that rely on gSOAP for XML and Web services coding: the much-debated Section 3.3.1 that Apple changed does not affect gSOAP usage. In fact, it may be a good reason to stick to gSOAP for native C and C++ code, rather than switching to a cross-platform toolkit to cross-compile from a different development platform or programming language (which is no longer allowed for applications developed for the iPhone and iPad). I plan to compile a user guide for gSOAP for the iPhone/iPad specializing on the use of NSSocket (recommended) instead of BSD sockets and other helpful things.


April 2010:

Released gSOAP 2.7.16. This release includes WS-ReliableMessaging, a new auto-test server code generation feature (soapcpp2 option -T), enhanced examples and documentation, and new features such as "colon notation" to bind namespace prefixes to C/C++ names.


September 2009:

The WS-I 1.1 and 1.2 basic profile reports are updated. See the reports.


August 2008:

As an educator I came across the book "Web Services: Principles and Technology" by Michael P. Papazoglou. I highly recommend it for its comprehensive examination of Web services and related technologies.


January 2008:

Web Services Without Pain: gSOAP Writes Your XML, SOAP, and RPC. Short article shows the merits of gSOAP to generate SOAP/XML applications: "gSOAP can literally shave weeks and many thousands of dollars off of the cost of developing new server-client software."


June 2007:

MultiXTpm is an Application Server, Message Oriented Middleware (MOM) and Transaction Processing (TP) Monitor. It provides the runtime environment and rich API for developing large, scalable distributed applications for OLTP. The MultiXTpm gSoap enhancer addsfunctionality on top of gSoap and MultiXTpm.


April 2007:

The W3C Databinding Interoperability Results are available, with gSOAP stats included thanks to Hugo Haas and the W3C XML Schema Patterns for Databinding Interoperability working group. The mission of the working group is to determine the coverage of XML schema constructs by data binding tools for programming languages and frameworks, which will tell implementors in the relevant domain which parts of schema users are most likely to expect them to support well. Update: we are pleased to report that gSOAP 2.7.17 passes 100% of the 294 tests, which sets it clearly apart from the other tools. The gSOAP auto-test echo server is included in the 2.7.17 package.


February 2007:

XML Journal SYS-CON article comparing gSOAP to other C/C++ Web services toolkits: Exposing SOA Enabled C Apps as Web Services by Mohit Chawla and Vijaya Bhaskar Peddinti.


November 2006:

Interested in using gSOAP Web service with UIQ 3 phones? Read Web services for UIQ 3 and gSOAP tutorial by Sony/Ericsson.


October 2006:

Read an introduction to gSOAP by Bo Xie from IBM with build instructions for MSVC++ 6.0: Use gSOAP to consume J2EE Web services created by WSAD through HTTP and HTTPS.


June 2006:

SOA World Magazine SYS-CON article on Leveraging gSOAP for Legacy Systems Integration by James Caple.


April 2006:

Surpassed 100,000 gSOAP toolkit downloads from SourceForge since 2003!


January 2006:

Pascal Botte shows how Lego Mindstorms fans can access the Lego RCX brick with gSOAP Web services. The new Lego Mindstorms NXT has arrived!


June 2005:

Are Web services scale free? Find out.


June 2005:

A recent patent granted to Microsoft on "XML Serialization" has caused some commotion, see XML serialization patent and prior art. The basis of the gSOAP software pre-dates Microsoft's XML serialization patent and is thus considered prior art: Gunjan Gupta's Master's project conducted in my research lab implemented an XML serialization algorithm in a compiler we developed for C, based on a SOAP and XML mapping that we developed in 1999. The project report TR-001205 was filed in the Department of Computer Science in 2000 before Microsoft's patent was filed. Shows that it is good we lead rather than follow (the Web services technology).


May 2005:

A feature article on gSOAP appeared in Linux Magazine for the Linux (and gSOAP!) enthousiasts in France.


February 2005:

See our feature article gSOAP & Web services in the C/C++ Users Journal February issue on Web Services and C++!


August 2004:

The gSOAP toolkit received a five star rating in all categories in a recent survey study of C++ Web services tools: see CRN survey article for more details.


July 2004:

iAnywhere/AvantGo are using gsoap for their M-Business Anywhere server. M-Business Anywhere provides a platform for delivering Web-based content and applications to a wide variety of mobile devices rapidly and cost-effectively with minimal recoding.


March 2004:

The release of Borland C++BuilderX 1.5 brings several new solutions for Symbian OS including the first, native C++, Rapid Application Development (RAD) support. A port of gSOAP will ease the job of enterprise developers who want to use Web Services to mobilize corporate data to Symbian OS phones. Read more.


December 2003:

New WSDL tools (WSDL parser, import, and generator) are released as part of the gSOAP 2.4 releases. The new WSDL parser includes many enhancements for developing SOAP 1.1/1.2 RPC, literal encoding, and document style Web services.


November 2003:

IBM released the IBM Tivoli Access Manager for e-business. The Tivoli Access Manager is an award winning, policy-based access control solution for e-business and enterprise applications. Part of the Tivoli Access Manager uses gSOAP.


November 2003:

The OFACSearch application developed with gSOAP by the Oasis Group is used to help companies comply with the Treasury Department's Office of Foreign Assets Control (OFAC) regulations.


October 2003:

Adobe's Version Cue, an innovative file-management feature of the recently unveiled Adobe Creative Suite, uses gSOAP as the foundation of its SOAP services client.


October 2003:

The BEA WebLogic Enterprise Security product line is family of security solutions that provide enhanced application security that includes policy-based delegated administration, authentication with single sign-on, consolidated auditing, and dynamic-role and policy-based authorization with delegation. Part of this product uses the gSOAP library.


October 2003:

Foundstone 3.0 Professional, an advanced network security analysis and protection tool, uses gSOAP as part of its data communication framework.


October 2003:

ObjectStore released its Real-Time Event Engine 3.0, a high-performance application solution for the real-time capture, organization and simultaneous query of streaming financial event data. The Event Engine combines extreme scalability with a flexible "Cache-Forward" architecture to support real-time analysis on streaming event data in distributed environments, without impacting capture or query speeds. The Real-Time Event Engine is based on gSOAP.


September 2003:

The AOL 9.0 YGP (You've Got Pictures) team used gSOAP to provide the foundation for the SOAP services client included in the AOL 9.0 product.


July 2003:

PalmSource in partnership with IBM offers a Web Services Toolkit for Mobile Devices based on gSOAP.
read more...


May 2002:

CapeClear article on Web Services for C and C++ Applications.


Getting Started

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 http://www.xmethods.net/wsdl/query.wsdl

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:  http://services.xmethods.net:80/soap
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 http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl

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: http://66.28.98.121:9090/soap
//gsoap ns1 service namespace: urn:xmethods-delayed-quotes
//gsoap ns1 service documentation: Definitions generated by the gSOAP WSDL parser 1.0
// Service net.xmethods.services.stockquote.StockQuoteService : net.xmethods.services.stockquote.StockQuote web service
//gsoap ns1 service method-style: getQuote rpc
//gsoap ns1 service method-encoding: getQuote http://schemas.xmlsoap.org/soap/encoding/
//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 
main() 

   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;
   else
      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> 
main() 

   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; 
   } 
   else
   { 
      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: