The gSOAP Toolkit for SOAP Web Services and XML-Based Applications
The gSOAP Toolkit for SOAP Web Services and XML-Based Applications
A cross-platform open source C and C++ software development toolkit. Generates C/C++ RPC code, XML data bindings, and efficient schema-specific parsers for SOAP Web services and other applications that benefit from an XML interface.
The gSOAP toolkit offers a comprehensive and transparent XML data binding solution for C and C++ through autocoding techniques. Autocoding saves developers substantial time to implement SOAP/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 gSOAP toolkit implements the 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 is effectively leveraged to ensure data content validation of SOAP messages and XML documents. Secondly, compiler-based schema-specific parsing is more efficient than most other XML parsing techniques.
The gSOAP toolkit also generates WSDL and XML schemas (XSD) for existing C/C++ data types and application functions, 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.
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:
- 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: over 150,000 downloads since 2003, over 5,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.
- All-in-one package: independence from third-party tools and libraries ensures successful builds and reliable runtime execution.
- Open source: free and commercial license options.
- C and C++ support: supports both pure ANSI C and mixed C/C++ application development.
- Comprehensive XML data bindings: gSOAP is the only SOAP/XML toolkit that supports a purely native C/C++ data binding to XML using automatic mappings for user-defined C and C++ data types without artificial frills. 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 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).
- Industry-standard protocols: SOAP 1.1/1.2 (RPC encoding and document/literal styles), WSDL 1.1, and UDDI v2. 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, MIME (SwA), DIME (streaming), MTOM (streaming), HTTP1.0/1.1, IPv4, IPv6, RSS, XML-RPC, WS-Addressing, WS-Enumeration, and many other WS-* protocols. 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 signatures.
- 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.
- 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 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 cannot disclose).
Recent News and Announcements on gSOAP
October 2008:
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.
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' 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.
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
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:
|
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 dump. You can also use Apache_mod, WinInet, IIS, or Fast CGI.
Citing gSOAP: Publications
When citing the gSOAP project, please cite the following paper that first introduced gSOAP:
- Robert A. van Engelen and Kyle Gallivan, The gSOAP Toolkit for Web Services and Peer-To-Peer Computing Networks, in the proceedings of the 2nd IEEE International Symposium on Cluster Computing and the Grid (CCGrid2002), pages 128-135, May 21-24, 2002, Berlin, Germany.
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.