Pelco Developer Network (PDN)

Generating ONVIF Proxy Classes using gSOAP

gSOAP is a commonly-used toolkit that simplifies web service application development. Among other features, gSOAP consumes WSDL files and generates source code for calling those WSDLs. One option creates C++ proxy classes that encapsulate most of the network connectivity functions, including construction of HTTP headers, requests, and responses. This frees the developer to focus on application functionality rather than infrastructure. This article illustrates the use of gSOAP to consume a specific ONVIF service and generate C++ proxy classes that can be used in an application.
 
gSOAP includes pre-built tools for all common operating systems. Plus, source code is included if you need to build your own. More information is provided in the README.txt and INSTALL.txt files included in the archive. The pre-built tools are in the gsoap/bin folder, as shown in Figure 1.
 

Figure 1. Location of common gSOAP tools.

 
After downloading and unpacking the gSOAP archive, follow these two steps to generate the classes:
  1. Run wsdl2h to generate header files from the WSDL file(s).
  2. Run soapcpp2 to generate the class files.
Both of these are command-line tools. The remainder of this article illustrates these steps in detail.
 

Run wsdl2h to generate header files

wsdl2h accepts a few flags and parameters that have significance for this project:
  • The -I flag specifies one or more search directories to include. In this example wsdl2h runs from the root of the gSOAP archive. It needs access to files in the gsoap subdirectory, which can be accomplished by including -I gsoap on the command-line.
  • The -o flag specifies the output header file to be written (onvif.h).
  • The final parameter is the path to the WSDL file. Note that this file (devicemgt.wsdl) is on the ONVIF web site. gSOAP transparently handles the fetch!
 
gsoap-2.8$ wsdl2h -I gsoap -o onvif.h http://www.onvif.org/onvif/ver10/device/wsdl/devicemgmt.wsdl

**  The gSOAP WSDL/Schema processor for C and C++, wsdl2h release 2.8.11
**  Copyright (C) 2000-2012 Robert van Engelen, Genivia Inc.
**  All Rights Reserved. This product is provided "as is", without any warranty.
**  The wsdl2h tool is released under one of the following two licenses:
**  GPL or the commercial license by Genivia Inc. Use option -l for details.

Saving onvif.h

Reading type definitions from type map file 'gsoap/typemap.dat'

Connecting to 'http://www.onvif.org/onvif/ver10/device/wsdl/devicemgmt.wsdl' to retrieve WSDL/XSD...
Connected, receiving...

Connecting to 'http://www.onvif.org/onvif/ver10/device/wsdl/../../../ver10/schema/onvif.xsd' to retrieve relative '../../../ver10/schema/onvif.xsd' schema...
Connected, receiving...
Done reading '../../../ver10/schema/onvif.xsd'

Connecting to 'http://docs.oasis-open.org/wsn/b-2.xsd' to retrieve schema...
Connected, receiving...
Done reading 'http://docs.oasis-open.org/wsn/b-2.xsd'

Connecting to 'http://docs.oasis-open.org/wsrf/bf-2.xsd' to retrieve schema...
Connected, receiving...
Done reading 'http://docs.oasis-open.org/wsrf/bf-2.xsd'

Connecting to 'http://docs.oasis-open.org/wsn/t-1.xsd' to retrieve schema...
Connected, receiving...
Warning: unexpected element 'xsd:unique' at level 2 is skipped (safe to ignore)
Warning: unexpected element 'xsd:unique' at level 6 is skipped (safe to ignore)
Done reading 'http://docs.oasis-open.org/wsn/t-1.xsd'
Done reading 'http://www.onvif.org/onvif/ver10/device/wsdl/devicemgmt.wsdl'

To complete the process, compile with:
> soapcpp2 onvif.h
or to generate C++ proxy and object classes:
> soapcpp2 -j onvif.h

gsoap-2.8$
 
wsdl2h prompts with the next step in the process, running soapcpp2.
 

Run soapcpp2 to generate source code files

soapcpp2 reads the header file generated by wsdl2h and creates header and source files for each web service call. Flags of interest include:
  • The -I flag specifies one or more search directories to include. This example includes the import and custom directories, and the current directory. Note the use of a colon ':' to delineate the paths on this platform; other platforms use a semicolon ';' instead.
  • The -d flag specifies the output directory (cpp_files). In this case there are a lot of output files, so a separate directory helps with housekeeping.
  • The -i flag generates C++ proxy classes with additional functionality compared to the older gSOAP style. The gSOAP documentation describes the differences in detail. Here is a comparison of the soapDeviceBindingProxy.h file, as generated without and with the flag.

Without the -i flag:

/// Invoke 'StartFirmwareUpgrade' of service 'DeviceBinding' and return error code (or SOAP_OK)

virtual int __tds__StartFirmwareUpgrade(_tds__StartFirmwareUpgrade *tds__StartFirmwareUpgrade, _tds__StartFirmwareUpgradeResponse *tds__StartFirmwareUpgradeResponse) { return soap ? soap_call___tds__StartFirmwareUpgrade(soap, endpoint, NULL, tds__StartFirmwareUpgrade, tds__StartFirmwareUpgradeResponse) : SOAP_EOM; };
 
With the -i flag:
 
/// Web service operation 'StartFirmwareUpgrade' (returns error code or SOAP_OK)

virtual int StartFirmwareUpgrade(_tds__StartFirmwareUpgrade *tds__StartFirmwareUpgrade, _tds__StartFirmwareUpgradeResponse *tds__StartFirmwareUpgradeResponse) { return this->StartFirmwareUpgrade(NULL, NULL, tds__StartFirmwareUpgrade, tds__StartFirmwareUpgradeResponse); }

virtual int StartFirmwareUpgrade(const char *endpoint, const char *soap_action, _tds__StartFirmwareUpgrade *tds__StartFirmwareUpgrade, _tds__StartFirmwareUpgradeResponse *tds__StartFirmwareUpgradeResponse);
 

The final parameter in the soapcpp2 command line is the path to the header file generated by wsdl2h.

 
gsoap-2.8$ cd gsoap
gsoap$ soapcpp2 -I import:custom:. -d cpp_files -i ../onvif.h

**  The gSOAP code generator for C and C++, soapcpp2 release 2.8.11
**  Copyright (C) 2000-2012, Robert van Engelen, Genivia Inc.
**  All Rights Reserved. This product is provided "as is", without any warranty.
**  The soapcpp2 tool is released under one of the following two licenses:
**  GPL or the commercial license by Genivia Inc.

Using project directory path: cpp_files/
Saving cpp_files/soapStub.h annotated copy of the input declarations
Using tds service name: DeviceBinding
Using tds service style: document
Using tds service encoding: literal
Using tds service location: http://localhost:80
Using tds schema namespace: http://www.onvif.org/ver10/device/wsdl
Saving cpp_files/soapDeviceBindingProxy.h client proxy class
Saving cpp_files/soapDeviceBindingProxy.cpp client proxy class
Saving cpp_files/soapDeviceBindingService.h service class
Saving cpp_files/soapDeviceBindingService.cpp service class
Saving cpp_files/DeviceBinding.GetServices.req.xml sample SOAP/XML request
Saving cpp_files/DeviceBinding.GetServices.res.xml sample SOAP/XML response
Saving cpp_files/DeviceBinding.GetServiceCapabilities.req.xml sample SOAP/XML request
Saving cpp_files/DeviceBinding.GetServiceCapabilities.res.xml sample SOAP/XML response
Saving cpp_files/DeviceBinding.GetDeviceInformation.req.xml sample SOAP/XML request
Saving cpp_files/DeviceBinding.GetDeviceInformation.res.xml sample SOAP/XML response
. . .
Saving cpp_files/DeviceBinding.StartFirmwareUpgrade.req.xml sample SOAP/XML request
Saving cpp_files/DeviceBinding.StartFirmwareUpgrade.res.xml sample SOAP/XML response
Saving cpp_files/DeviceBinding.StartSystemRestore.req.xml sample SOAP/XML request
Saving cpp_files/DeviceBinding.StartSystemRestore.res.xml sample SOAP/XML response
Saving cpp_files/DeviceBinding.nsmap namespace mapping table
Saving cpp_files/soapH.h interface declarations
Saving cpp_files/soapC.cpp XML serializers

Compilation successful 

gsoap$
 

Copy the header and source files to the project directory, or add the gSOAP directories to the search path in the IDE or build tools you are using.

The examples presented here should get you started creating C++ classes to use in your own web service applications.

For More Information...

The following links contain additional information that will assist you in using gSOAP with WSDL files.