gSOAP 2.8.66 User Guide Robert van Engelen Genivia Inc www.genivia.com April 8, 2018 Contents 1 Introduction 8 1.1 Getting Started . 8 1.2 Quick Start: Developing a Web Service Client Application . 9 1.3 Quick Start: Developing a Web Service . 11 1.4 Quick Start: XML Data Bindings . 14 1.5 Feature Overview . 17 2 Notational Conventions 19 3 Differences Between gSOAP Versions 2.4 (and Earlier) and 2.5 19 4 Differences Between gSOAP Versions 2.1 (and Earlier) and 2.2 20 5 Differences Between gSOAP Versions 1.X and 2.X 20 6 Interoperability 22 7 Quick User Guide 23 7.1 How to Build SOAP/XML Clients . 23 7.1.1 Example . 25 7.1.2 XML Namespace Considerations . 31 7.1.3 Example . 33 7.1.4 How to Generate C++ Client Proxy Classes . 34 7.1.5 XSD Type Encoding Considerations . 36 7.1.6 Example . 36 7.1.7 How to Change the Response Element Name . 37 1 7.1.8 Example . 37 7.1.9 How to Specify Multiple Output Parameters . 38 7.1.10 Example . 38 7.1.11 How to Specify Output Parameters With struct/class Compound Data Types ...................................... 40 7.1.12 Example . 40 7.1.13 How to Specify Anonymous Parameter Names . 42 7.1.14 How to Specify a Method with No Input Parameters . 43 7.1.15 How to Specify a Method with No Output Parameters . 44 7.2 How to Build SOAP/XML Web Services . 44 7.2.1 Example . 44 7.2.2 MSVC++ Builds . 47 7.2.3 How to Create a Stand-Alone Server . 47 7.2.4 How to Create a Multi-Threaded Stand-Alone Service . 49 7.2.5 How to Pass Application Data to Service Methods . 55 7.2.6 Web Service Implementation Aspects . 55 7.2.7 How to Generate C++ Server Object Classes . 56 7.2.8 How to Chain C++ Server Classes to Accept Messages on the Same Port 58 7.2.9 How to Generate WSDL Service Descriptions . 60 7.2.10 Example . 61 7.2.11 How to Use Client Functionalities Within a Service . 63 7.3 Asynchronous One-Way Message Passing . 65 7.4 Implementing Synchronous One-Way Message Passing over HTTP . 66 7.5 How to Use the SOAP Serializers and Deserializers to Save and Load Application Data using XML Data Bindings . 67 7.5.1 Mapping XML Schema to C/C++ with wsdl2h . 67 7.5.2 Mapping C/C++ to XML Schema with soapcpp2 . 70 7.5.3 Serializing C/C++ Data to XML . 72 7.5.4 Deserializing C/C++ Data from XML . 78 7.5.5 Example . 80 7.5.6 Serializing and Deserializing Class Instances to Streams . 84 7.5.7 How to Specify Default Values for Omitted Data . 85 8 The wsdl2h WSDL and Schema Importer 86 8.1 wsdl2h Options . 88 8.2 Customizing Data Bindings With The typemap.dat File . 90 2 9 Using the soapcpp2 Compiler and Code Generator 92 9.1 soapcpp2 Options . 93 9.2 SOAP 1.1 Versus SOAP 1.2 and Dynamic Switching . 95 9.3 The soapdefs.h Header File . 96 9.4 How to Build Modules and Libraries with the #module Directive . 97 9.5 How to use the #import Directive . 98 9.6 How to Use #include and #define Directives . 98 9.7 Compiling a SOAP/XML Client Application with soapcpp2 . 99 9.8 Compiling a SOAP/XML Web Service with soapcpp2 . 100 9.9 Compiling Web Services and Clients in ANSI C . 100 9.10 Limitations of gSOAP . 101 9.11 Library Build Flags . 102 9.12 Run Time Flags . 104 9.13 Memory Management . 107 9.13.1 Memory Allocation and Management Policies . 108 9.13.2 Intra-Class Memory Management . 110 9.14 Debugging . 112 9.15 Generating an Auto Test Server for Client Testing . 113 9.16 Generating Deep Copy and Deletion Code . 113 9.17 Required Libraries . 114 10 The gSOAP Service Operation Specification Format 114 10.1 Service Operation Parameter Passing . 116 10.2 Error Codes . 117 10.3 C/C++ Identifier Name to XML Tag Name Mapping . 120 10.4 Namespace Mapping Table . 124 11 gSOAP Serialization and Deserialization Rules 126 11.1 SOAP RPC Encoding Versus Document/Literal and xsi:type Info . 126 11.2 Primitive Type Encoding . 127 11.3 How to Represent Primitive C/C++ Types as XSD Types . 128 11.3.1 How to Use Multiple C/C++ Types for a Single Primitive XSD Type . 134 11.3.2 How to use C++ Wrapper Classes to Specify Polymorphic Primitive Types134 11.3.3 XSD Schema Type Decoding Rules . 136 11.3.4 Multi-Reference Strings . 139 11.3.5 \Smart String" Mixed-Content Decoding . 139 11.3.6 C++ Strings . 140 11.3.7 Changing the Encoding Precision of float and double Types . 140 11.3.8 INF, -INF, and NaN Values of float and double Types . 141 3 11.4 Enumeration Serialization . 142 11.4.1 Serialization of Symbolic Enumeration Constants . 142 11.4.2 Encoding of Enumeration Constants . 143 11.4.3 Initialized Enumeration Constants . 143 11.4.4 How to \Reuse" Symbolic Enumeration Constants . 143 11.4.5 Boolean Enumeration Serialization for C . 144 11.4.6 Bitmask Enumeration Serialization . 145 11.5 Struct Serialization . 145 11.6 Class Instance Serialization . 146 11.6.1 Example . 147 11.6.2 Initialized static const Fields . 148 11.6.3 Class Methods . 149 11.6.4 Getter and Setter Methods . 149 11.6.5 Streaming XML with Getter and Setter Methods . 150 11.6.6 Polymorphism, Derived Classes, and Dynamic Binding . 151 11.6.7 XML Attributes . 154 11.6.8 QName Attributes and Elements . 155 11.7 Union Serialization . 156 11.8 Serializing Pointer Types . 158 11.8.1 Multi-Referenced Data . 158 11.8.2 NULL Pointers and Nil Elements . 159 11.9 Void Pointers . 160 11.10Fixed-Size Arrays . 161 11.11Dynamic Arrays . 162 11.11.1 SOAP Array Bounds Limits . 162 11.11.2 One-Dimensional Dynamic SOAP Arrays . 162 11.11.3 Example . 163 11.11.4 One-Dimensional Dynamic SOAP Arrays With Non-Zero Offset . 165 11.11.5 Nested One-Dimensional Dynamic SOAP Arrays . 166 11.11.6 Multi-Dimensional Dynamic SOAP Arrays . 167 11.11.7 Encoding XML Generics Containing Dynamic Arrays . 168 11.11.8 STL Containers . 170 11.11.9 Polymorphic Dynamic Arrays and Lists . 173 11.11.10How to Change the Tag Names of the Elements of a SOAP Array or List 174 11.12Base64Binary XML Schema Type Encoding . 175 11.13hexBinary XML Schema Type Encoding . 177 11.14Literal XML Encoding Style . 178 11.14.1 Serializing and Deserializing Mixed Content XML With Strings . 180 4 12 SOAP Fault Processing 181 13 SOAP Header Processing 184 14 MIME Attachments 186 14.1 Sending a Collection of MIME Attachments (SwA) . 186 14.2.