The gSOAP Toolkit for SOAP and REST Web Services and XML-Based Applications
Translate to Portuguese
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++
The toolkit supports options to generate pure ANSI C or C++ with or without
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. There is also another older how-to start with gSOAP.
User Guide: the guide with everything gSOAP. But you may want to start with understanding XML Data Bindings
Fact Sheet: a quick
overview of key features.
Licensing: dual licensed as open source GPL v2 and commercial-use license (available for purchase).
Download: get started today.
Why use gSOAP?
Here is a summary of 16 reasons why we believe you may want to try gSOAP for
- 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.
- 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.
- Broad user base: about one million downloads since 2003, over 6,000
mailing list members, and thousands of license/support agreements with
companies. Here is a brief selection
of the success stories and a summary of user testimonials.
- All-in-one package: independence from third-party tools and
libraries ensures successful builds and reliable runtime execution.
- Open source: free open source for non-commercial use (GPL v2).
Commercial-use licensing available for purchase.
- C and C++ support: supports both pure ANSI C and mixed C/C++
- 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).
- 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
- 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).
- 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.
- Security: HTTPS and WS-Security: authentication, tokens, digital
- 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.
- 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.
- 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.
- Numerous examples: the software package includes many code examples,
including stand-alone HTTP/1.1 and HTTPS-secure Web Server.
- Web server integration: includes Apache_mod, IIS, WinInet, CGI, and
FastCGI interfaces to integrate your services.
- 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
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
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.
- The 'wsdl2h' WSDL parser. This tool converts WSDLs and XSD files into
annotated C/C++ definitions.
- The 'soapcpp2' stub and skeleton compiler. This tool generates RPC code
and XML serializers from the annotated C/C++ definitions.
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
|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
|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
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.
The XMethods Delayed Stock Quote Web Service provides a delayed stock quote
for a given ticker name, see XMethods Delayed Stock
for details. The WSDL description of the Delayed Stock Quote Web Service provides
the following details:
||"" (2 quotes)
|Remote method namespace:
|Remote method name:
| 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://184.108.40.206: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:
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();
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
if (q.ns1__getQuote("IBM", r) == SOAP_OK)
std::cout << r << std::endl;
This assumes that the code was produced by omitting the -c option for 'wsdl2h'
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):
The add and sub methods are intended to add and subtract
two double floating point numbers stored in input parameters
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
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:
|// 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
int ns__sub(double a, double b, double
int ns__sqrt(double a, double &result);
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
The implementation of the remote methods return a SOAP status code. The
code SOAP_OK denotes success, while
soap_sender_fault returns an
This application is intended to run as a CGI application at the specified
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.
|// Contents of file "calc.cpp":
soap_serve(soap_new()); // call the incoming remote method request
// Implementation of the "add" remote method:
int ns__add(struct soap *soap, double a, double b, double
result = a + b;
// Implementation of the "sub" remote method:
int ns__sub(struct soap *soap, double a, double b, double
result = a - b;
// Implementation of the "sqrt" remote method:
int ns__sqrt(struct soap *soap, double a, double &result)
if (a >= 0)
result = sqrt(a);
"Square root of negative value", "I can only compute the square root of a
Citing gSOAP: Publications
When citing the gSOAP project, please cite the following paper that first introduced gSOAP:
Other gSOAP and Web services-related publications:
- Robert A. van Engelen, Pushing the SOAP Envelope with Web Services for Scientific Computing, in the proceedings of the International Conference on Web Services (ICWS), 2003, pages 346-354.
- Robert van Engelen, Gunjan Gupta, and Saurabh Pant, Developing Web Services for C and C++, in IEEE Internet Computing Journal, March, 2003, pages 53-61.
- Giovanni Aloisio, Massimo Cafaro, Daniele Lezzi, and Robert van Engelen, Secure Web Services with Globus GSI and gSOAP, in the proceedings of EUROPAR 2003.
- Robert van Engelen, Code Generation Techniques for Developing Web Services for Embedded Devices, in the proceedings of the 9th ACM Symposium on Applied Computing SAC, Nicosia, Cyprus, 2004, pages 854-861.
- Robert van Engelen, Constructing Finite State Automata for High Performance XML Web Services, in the proceedings of the International Symposium on Web Services (ISWS), 2004, pages 975-981.
- M. Govindaraju, A. Slominski, K. Chiu, P. Liu, R. van Engelen, and M. Lewis, Toward Characterizing the Performance of SOAP Toolkits, in the proceedings of the 5th IEEE/ACM International Workshop on Grid Computing, pages 365-372, Pittsburgh, USA, 2004.
- Giovanni Aloisio, Massimo Cafaro, Italo Epicoco, Daniele Lezzi, and Robert van Engelen, The GSI plug-in for gSOAP: Enhanced Security, Performance, and Reliability, in the ITCC conference 2005, IEEE Press, Volume I, pages 304-309.
- Michael R. Head, Madhusudhan Govindaraju, Aleksander Slominski, Pu Liu, Nayef Abu-Ghazaleh, Robert van Engelen, Kenneth Chiu, Michael J. Lewis, Benchmark Suite for SOAP-based Communication in Grid Web Services , in the proceedings of ACM/IEEE Supercomputing (SC), 2005.
- Robert van Engelen, Wei Zhang, and Madhusudhan Govindaraju, Toward Remote Object Coherence with Compiled Object Serialization for Distributed Computing with XML Web Services, in the proceedings of Compilers for Parallel Computing (CPC), 2006, pages 441-455.
- Wei Zhang and Robert van Engelen, TDX: a High-Performance Table-Driven XML Parser, in the proceedings of the ACM SouthEast conference, 2006, pages 726-731.
- Wei Zhang and Robert van Engelen, A Table-Driven XML Streaming Methodology for High-Performance Web Services, in the proceedings of IEEE International Conference on Web Services (ICWS), 2006, pages 197-206, (best student paper award).
- Robert van Engelen, Madhusudhan Govindaraju, and Wei Zhang, Exploring Remote Object Coherence in XML Web Services, in proceedings of IEEE International Conference on Web Services (ICWS), 2006, pages 249-256.
- M. Head, M. Govindaraju , R. van Engelen, and W. Zhang, Benchmarking XML Processors for Applications in Grid Web Services, in the proceedings of Supercomputing 2006.
- M. Cafaro, D. Lezzi, S. Fiore, G. Aloisio, and R. van Engelen, The GSI plug-in for gSOAP: building cross-grid interoperable secure grid services, in the proceedings of the 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, pages 894-901, 2008.
- Robert van Engelen and Wei Zhang, An Overview and Evaluation of Web Services Security Performance Optimizations, to appear in the proceedings of the IEEE International Conference on Web Services (ICWS), 2008.
- Wei Zhang and Robert van Engelen, High-Performance XML Parsing and Validation with Permutation Phrase Grammar Parsers, to appear in the proceedings of the IEEE International Conference on Web Services (ICWS), 2008.
- Robert A. van Engelen and Wei Zhang, Identifying Opportunities for Web Services Security Performance Optimizations, to appear in the proceedings of the IEEE Services Computing Conference (SCC), 2008.
- Robert A. van Engelen, A Framework for Service-Oriented Computing with C and C++ Web Service Components, ACM Transactions on Internet Technologies, Volume 8, Issue 3, Article 12, May 2008.