gSOAP 2.7.10 User Guide Robert van Engelen Florida State University and Genivia, Inc. [email protected] & [email protected] February 4, 2008 Contents 1 Introduction 8 1.1 Getting Started . 8 1.2 Your First Web Service Client Application . 9 1.3 Your First Web Service in CGI . 10 1.4 Features . 11 2 Notational Conventions 13 3 Differences Between gSOAP Versions 2.4 (and Earlier) and 2.5 13 4 Differences Between gSOAP Versions 2.1 (and Earlier) and 2.2 14 5 Differences Between gSOAP Versions 1.X and 2.X 14 6 Interoperability 16 7 Quick User Guide 17 7.1 How to Use the gSOAP Stub and Skeleton Compiler to Build SOAP Clients . 18 7.1.1 Example . 19 7.1.2 Namespace Considerations . 23 7.1.3 Example . 24 7.1.4 How to Generate C++ Client Proxy Classes . 25 7.1.5 XSD Type Encoding Considerations . 27 7.1.6 Example . 28 7.1.7 How to Change the Response Element Name . 29 7.1.8 Example . 29 1 7.1.9 How to Specify Multiple Output Parameters . 30 7.1.10 Example . 30 7.1.11 How to Specify Output Parameters With struct/class Compound Data Types ...................................... 31 7.1.12 Example . 31 7.1.13 How to Specify Anonymous Parameter Names . 34 7.1.14 How to Specify a Method with No Input Parameters . 35 7.1.15 How to Specify a Method with No Output Parameters . 35 7.2 How to Use the gSOAP Stub and Skeleton Compiler to Build SOAP Web Services 36 7.2.1 Example . 36 7.2.2 MSVC++ Builds . 38 7.2.3 How to Create a Stand-Alone gSOAP Service . 39 7.2.4 How to Create a Multi-Threaded Stand-Alone Service . 41 7.2.5 How to Pass Application Data to Service Methods . 47 7.2.6 Some Web Service Implementation Issues . 47 7.2.7 How to Generate C++ Server Object Classes . 48 7.2.8 How to Generate WSDL Service Descriptions . 49 7.2.9 Example . 49 7.2.10 How to Parse and Import WSDL Service Descriptions to Develop Clients and Servers . 52 7.2.11 The typemap.dat File . 53 7.2.12 How to Use Client Functionalities Within a Service . 54 7.3 How to Use gSOAP for Asynchronous One-Way Message Passing . 57 7.4 One-Way Message Passing over HTTP . 58 7.5 How to Use the SOAP Serializers and Deserializers to Save and Load Application Data . 58 7.5.1 Serializing a Data Type . 59 7.5.2 Deserializing a Data Type . 64 7.5.3 Example . 65 7.5.4 Serializing and Deserializing Class Instances to Streams . 69 7.5.5 How to Specify Default Values for Omitted Data . 70 8 Using the gSOAP Stub and Skeleton Compiler 72 8.1 Compiler Options . 73 8.2 SOAP 1.1 Versus SOAP 1.2 . 74 8.3 The soapdefs.h Header File . 75 8.4 How to Build Modules and Libraries with the gSOAP #module Directive . 75 8.5 How to use the gSOAP #import Directive . 76 8.6 How to Use #include and #define Directives . 77 2 8.7 Compiling a gSOAP Client . 77 8.8 Compiling a gSOAP Web Service . 78 8.9 Using gSOAP for Creating Web Services and Clients in Pure C . 79 8.10 Limitations of gSOAP . 79 8.11 Compile Time Flags . 81 8.12 Run Time Flags . 81 8.13 Memory Management . 83 8.13.1 Memory Management Policies . 84 8.13.2 Intra-Class Memory Management . 87 8.14 Debugging . 88 8.15 Required Libraries . 89 9 The gSOAP Remote Method Specification Format 90 9.1 Remote Method Parameter Passing . 91 9.2 Error Codes . 92 9.3 C/C++ Identifier Name to XML Name Translations . 95 9.4 Namespace Mapping Table . 96 10 gSOAP Serialization and Deserialization Rules 99 10.1 SOAP RPC Encoding Versus Document/Literal and xsi:type Info . 99 10.2 Primitive Type Encoding . 99 10.3 How to Represent Primitive C/C++ Types as XSD Types . 100 10.3.1 How to Use Multiple C/C++ Types for a Single Primitive XSD Type . 107 10.3.2 How to use Wrapper Classes to Specify Polymorphic Primitive Types . 107 10.3.3 XSD Schema Type Decoding Rules . 109 10.3.4 Multi-Reference Strings . 112 10.3.5 \Smart String" Mixed-Content Decoding . 112 10.3.6 STL Strings . 113 10.3.7 Changing the Encoding Precision of float and double Types . 113 10.3.8 INF, -INF, and NaN Values of float and double Types . 114 10.4 Enumeration Serialization . 114 10.4.1 Serialization of Symbolic Enumeration Constants . 114 10.4.2 Encoding of Enumeration Constants . 115 10.4.3 Initialized Enumeration Constants . 116 10.4.4 How to \Reuse" Symbolic Enumeration Constants . 116 10.4.5 Boolean Enumeration Serialization for C . 117 10.4.6 Bitmask Enumeration Serialization . 117 10.5 Struct Serialization . 118 10.6 Class Instance Serialization . 118 3 10.6.1 Example . 120 10.6.2 Initialized static const Fields . 120 10.6.3 Class Methods . 121 10.6.4 Getter and Setter Methods . 121 10.6.5 Streaming XML with Getter and Setter Methods . 122 10.6.6 Polymorphism, Derived Classes, and Dynamic Binding . 123 10.6.7 XML Attributes . 126 10.6.8 QName Attributes and Elements . 128 10.7 Union Serialization . 128 10.8 Serializing Pointer Types . 130 10.8.1 Multi-Referenced Data . 130 10.8.2 NULL Pointers and Nil Elements . 131 10.9 Void Pointers . 132 10.10Fixed-Size Arrays . 133 10.11Dynamic Arrays . 134 10.11.1 SOAP Array Bounds Limits . 134 10.11.2 One-Dimensional Dynamic Arrays . 134 10.11.3 Example . 135 10.11.4 One-Dimensional Dynamic Arrays With Non-Zero Offset . 137 10.11.5 Nested One-Dimensional Dynamic Arrays . 138 10.11.6 Multi-Dimensional Dynamic Arrays . 139 10.11.7 Encoding XML Generics Containing Dynamic Arrays . 140 10.11.8 STL Containers . 141 10.11.9 Polymorphic Dynamic Arrays and Lists . 144 10.11.10How to Change the Tag Names of the Elements of a SOAP Array or List 144 10.12Base64Binary XML Schema Type Encoding . 145 10.13hexBinary XML Schema Type Encoding . 147 10.14Literal XML Encoding Style . 147 10.14.1 Serializing and Deserializing Mixed Content XML With Strings . 149 11 SOAP Fault Processing 151 12 SOAP Header Processing 153 13 MIME Attachments 155 13.1 Sending a Collection of MIME Attachments (SwA) . 156 13.2 Retrieving a Collection of MIME Attachments (SwA) . 158 4 14 DIME Attachments 159 14.1 Sending a Collection of DIME Attachments . 159 14.2 Retrieving a Collection of DIME Attachments . ..