gSOAP 2.7.0 User Guide Robert van Engelen Genivia, Inc., [email protected] & [email protected] October 15, 2004 Contents 1 Introduction 6 2 Notational Conventions 7 3 Differences Between gSOAP Versions 2.4 (and Earlier) and 2.5 8 4 Differences Between gSOAP Versions 2.1 (and Earlier) and 2.2 8 5 Differences Between gSOAP Versions 1.X and 2.X 8 6 Interoperability 11 7 Getting Started 12 8 Quick User Guide 12 8.1 How to Use the gSOAP Stub and Skeleton Compiler to Build SOAP Clients . 13 8.1.1 Example . 14 8.1.2 Namespace Considerations . 18 8.1.3 Example . 19 8.1.4 How to Generate C++ Client Proxy Classes . 20 8.1.5 XSD Type Encoding Considerations . 22 8.1.6 Example . 22 8.1.7 How to Change the Response Element Name . 23 8.1.8 Example . 23 8.1.9 How to Specify Multiple Output Parameters . 24 8.1.10 Example . 24 8.1.11 How to Specify Output Parameters With struct/class Compound Data Types ...................................... 26 8.1.12 Example . 26 1 8.1.13 How to Specify Anonymous Parameter Names . 28 8.1.14 How to Specify a Method with No Input Parameters . 29 8.1.15 How to Specify a Method with No Output Parameters . 30 8.2 How to Use the gSOAP Stub and Skeleton Compiler to Build SOAP Web Services 30 8.2.1 Example . 30 8.2.2 MSVC++ Builds . 33 8.2.3 How to Create a Stand-Alone gSOAP Service . 33 8.2.4 How to Create a Multi-Threaded Stand-Alone Service . 35 8.2.5 How to Pass Application Data to Service Methods . 38 8.2.6 Some Web Service Implementation Issues . 38 8.2.7 How to Generate C++ Server Object Classes . 38 8.2.8 How to Generate WSDL Service Descriptions . 39 8.2.9 Example . 40 8.2.10 How to Parse and Import WSDL Service Descriptions to Develop Clients and Servers . 43 8.2.11 How to Use Client Functionalities Within a Service . 45 8.3 How to Use gSOAP for Asynchronous One-Way Message Passing . 47 8.4 How to Use the SOAP Serializers and Deserializers to Save and Load Application Data . 48 8.4.1 Serializing a Data Type . 48 8.4.2 Deserializing a Data Type . 52 8.4.3 Example . 54 8.4.4 Serializing and Deserializing Class Instances to Streams . 57 8.4.5 How to Specify Default Values for Omitted Data . 59 9 Using the gSOAP Stub and Skeleton Compiler 60 9.1 Compiler Options . 61 9.2 SOAP 1.1 Versus SOAP 1.2 . 62 9.3 The soapdefs.h Header File . 63 9.4 How to Build Modules and Libraries with the gSOAP #module Directive . 64 9.5 How to use the gSOAP #import Directive . 65 9.6 How to Use #include and #define Directives . 65 9.7 Compiling a gSOAP Client . 66 9.8 Compiling a gSOAP Web Service . 66 9.9 Using gSOAP for Creating Web Services and Clients in Pure C . 67 9.10 Limitations of gSOAP . 67 9.11 Compile Time Flags . 69 9.12 Run Time Flags . 69 9.13 Memory Management . 71 9.13.1 Memory Management Policies . 72 2 9.13.2 Intra-Class Memory Management . 74 9.14 Debugging . 75 9.15 Libraries . 76 10 The gSOAP Remote Method Specification Format 77 10.1 Remote Method Parameter Passing . 78 10.2 Error Codes . 79 10.3 C/C++ Identifier Name to XML Name Translations . 82 10.4 Namespace Mapping Table . 83 11 gSOAP Serialization and Deserialization Rules 85 11.1 Primitive Type Encoding . 85 11.2 How to Encode and Decode Primitive Types as XSD Types . 85 11.2.1 How to Use Multiple C/C++ Types for a Single Primitive XSD Type . 92 11.2.2 How to use Wrapper Classes to Specify Polymorphic Primitive Types . 92 11.2.3 XML Schema Type Decoding Rules . 94 11.2.4 Multi-Reference Strings . 97 11.2.5 \Smart String" Mixed-Content Decoding . 97 11.2.6 STL Strings . 98 11.2.7 Changing the Encoding Precision of float and double Types . 98 11.2.8 INF, -INF, and NaN Values of float and double Types . 99 11.3 Enumeration Type Encoding and Decoding . 99 11.3.1 Symbolic Encoding of Enumeration Constants . 99 11.3.2 Encoding of Enumeration Constants . 100 11.3.3 Initialized Enumeration Constants . 101 11.3.4 How to \Reuse" Symbolic Enumeration Constants . 101 11.3.5 Boolean Enumeration Type Encoding and Decoding for C Compilers . 101 11.3.6 Bitmask Enumeration Encoding and Decoding . 102 11.4 Struct Encoding and Decoding . 102 11.5 Class Instance Encoding and Decoding . 103 11.5.1 Example . 104 11.5.2 Initialized static const Fields . 105 11.5.3 Class Methods . 105 11.5.4 Getter and Setter Methods . 106 11.5.5 Streaming XML with Getter and Setter Methods . 107 11.5.6 Polymorphism, Derived Classes, and Dynamic Binding . 107 11.5.7 XML Attributes . 111 11.5.8 QName Attributes and Elements . 112 11.6 Pointer Encoding and Decoding . 113 11.6.1 Multi-Reference Data . 113 3 11.6.2 NULL Pointers and Nil Elements . 114 11.7 Void Pointers . 114 11.8 Fixed-Size Arrays . 116 11.9 Dynamic Arrays . 116 11.9.1 SOAP Array Bounds Limits . 117 11.9.2 One-Dimensional Dynamic Arrays . 117 11.9.3 Example . 118 11.9.4 One-Dimensional Dynamic Arrays With Non-Zero Offset . 119 11.9.5 Nested One-Dimensional Dynamic Arrays . 120 11.9.6 Multi-Dimensional Dynamic Arrays . 121 11.9.7 Encoding XML Generics Containing Dynamic Arrays . 122 11.9.8 STL Containers . 124 11.9.9 Polymorphic Dynamic Arrays and Lists . 126 11.9.10 How to Change the Tag Names of the Elements of a SOAP Array or List 126 11.10Base64Binary XML Schema Type Encoding . 127 11.11hexBinary XML Schema Type Encoding . 129 11.12Literal XML Encoding Style . 129 11.12.1 Serializing and Deserializing Mixed Content XML With Strings . 131 12 SOAP Fault Processing 133 13 SOAP Header Processing 135 14 MIME Attachments 137 14.1 Sending a Collection of MIME Attachments . 137 14.2 Retrieving a Collection of MIME Attachments . 139 14.3 WSDL Bindings for MIME Attachments . 140 15 DIME Attachments 140 15.1 Sending a Collection of DIME Attachments . 141 15.2 Retrieving a Collection of DIME Attachments . 141 15.3 Serializing Binary Data in DIME . 142 15.4 Streaming DIME . 144 15.5 Streaming Chunked DIME . 148 15.6 WSDL Bindings for DIME Attachments . 148 16 XML Validation 148 16.1 Occurrence Constraints . 148 16.1.1 Elements with minOccurs and maxOccurs Restrictions . 148 16.1.2 Required and Prohibited Attributes . 149 16.1.3 Data Length Restrictions . 149 16.2 Other Constraints . ..