A quick how-to tutorial

The gSOAP toolkit simplifies the development and deployment of SOAP/XML Web Services and client applications in C and C++. The gSOAP RPC compiler does all the difficult work for you. It generates the necessary C and C++ source codes to seamlessly glue your C/C++ applications to the SOAP/XML Web Services stack. With the compiler you can enable your (existing) C and/or C++ applications to "talk SOAP"!.

gSOAP is not just a class library. The gSOAP RPC compiler produces routines to encode native and user-defined C/C++ types in XML. To make things even easier, gSOAP provides memory management with garbage collection so (XML-decoded) data can be cleaned up without a hassle.

How to develop a SOAP/XML Web Service with gSOAP

To develop a Web Service application, simply run the gSOAP compiler on a C/C++ header file that contains the function prototypes of the application functions that you want to expose as SOAP/XML Web Service methods. The compiler produces the skeleton routines to expose your application as a Web Service illustrated below. The compiler also generates a WSDL file that can be readily used to advertize your Web Service.

The gSOAP runtime library provides DIME, SOAP/XML, HTTP, HTTPS, and TCP/IP stacks.

Suppose for example that you have an application function called rate() that takes the URL of a Web site and returns a floating point rating of the site:

double rate(char *URL)

Your application code provides the implementation of rate(), which could be based on a database lookup. This implementation provides the Web Service logic at run time when your Web Service is deployed.

Because SOAP/XML Web Services use the power and expressiviness of XML, including XML schemas and namespaces, you will have to associate an XML namespace with your Web Service. The namespace is just a string that acts as an identification. In most cases, a URL to your site will suffice. This association requires binding a namespace prefix, say 'ns', to a namespace, say 'http://www.mysite.com'. The C/C++ header file specification of your service will consist of two items: the service namespace association and the function prototype(s) of your service methods:

//gsoap ns service namespace: http://www.mysite.com
int ns__rate(char *URL, double *rate);

Note that we used the prefix 'ns' with the function name. All function parameters will be considered input parameters, except the last (see the gSOAP documentation for further details). The return value is always int, which is used for error diagnostics. Now you need to run the gSOAP RPC compiler (soapcpp2) on this header file within your favorite IDE. This produces all the glue code (soapH.h, soapC.cpp, and soapClient.cpp) to deploy your Web Service.

Your service application code should include an implementation of ns__rate() as follows:

int ns__rate(struct soap *soap, char *URL, double *rate)
{ *rate = rate(URL);
  if (*rate >= 0)
    return SOAP_OK;
  return soap_sender_fault(soap, "Cannot rate this site", URL);
}

This function is automatically called when a client connects to your service with a request. The SOAP_OK return value indicates that the call could be completed. The soap_sender_fault returns a SOAP Fault to the sender. The call uses the soap struct run-time environment to temporarily allocate memory that will be released when the service invocation completes.

To deploy this Web Service as a CGI application, we need to call soap_serve in the main function:

int main()
{ return soap_serve(soap_new());
}

So here is the entire service code:

#include "soapH.h" /* get gSOAP-generated service definitions */
#include "ns.nsmap" /* get the XML service namespace bindings */
int main()
{ return soap_serve(soap_new());
}
int ns__rate(struct soap *soap, char *URL, double *rate)
{ *rate = rate(URL);
  if (*rate >= 0)
    return SOAP_OK;
  return soap_sender_fault(soap, "Cannot rate this site", URL);
}

The code is compiled and linked with stdsoap2.c (or stdsoap2.cpp). The executable is then installed and deployed as a CGI or FastCGI application. See the gSOAP documentation on how to deploy CGI applications and stand-alone gSOAP services.

Consider for example the XMethods Delayed Stock Quote Web Service. It provides a delayed stock quote for a given ticker name. The WSDL description of the Delayed Stock Quote Web Service provides the following details:

The gSOAP WSDL importer produces the following getQuote.h header file that includes the declarations of the remote method:

//gsoap ns service name: StockQuoteService
//gsoap ns service namespace: urn:xmethods-delayed-quotes
int ns__getQuote(char *symbol, float *result);

The service method is declared as a ns__getQuote function. This specifies all of the necessary details for the gSOAP RPC compiler to produce a client proxy object (and RPC stubs for pure C applications). The proxy (and stubs) enable the interaction with the Delayed Stock Quote service from within any C or C++ application. An example C client application code is illustrated below:

#include "soapH.h" /* get gSOAP-generated definitions */
#include "StockQuoteService.nsmap" /* get service namespace bindings */
int main()
{ struct soap *soap = soap_new();
  float quote;
  if (soap_call_ns__getQuote(soap, "http://services.xmethods.net:80/soap", "", "AOL", &quote) == SOAP_OK) 
    printf("Current AOL Stock Quote = %f\n", quote);  
  else
    soap_print_fault(soap, stderr); /* print SOAP fault */
}

An example C++ client application code that uses the proxy is:

#include "soapStockQuoteServiceProxy.h" /* get the gSOAP-generated proxy */
#include "StockQuoteService.nsmap" /* get service namespace bindings */
int main()
{ StockQuoteService stock;
  float quote;
  if (stock.getQuote("AOL", &quote) == SOAP_OK) 
    cout << "Current AOL Stock Quote = " << quote;  
  else
    soap_print_fault(soap, stderr); /* print SOAP fault */
}