gSOAP 2.8.14 User Guide
Robert van Engelen
GENIVIA INC
February 3, 2013
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 19
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7.1.4 How to Generate C++ Client Proxy Classes . . . . . . . . . . . . . . . . . 33
7.1.5 XSD Type Encoding Considerations . . . . . . . . . . . . . . . . . . . . . 35
7.1.6 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.1.7 How to Change the Response Element Name . . . . . . . . . . . . . . . . 37
7.1.8 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
1
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.1.12 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.1.13 How to Specify Anonymous Parameter Names . . . . . . . . . . . . . . . 42
7.1.14 How to Specify a Method with No Input Parameters . . . . . . . . . . . . 42
7.1.15 How to Specify a Method with No Output Parameters . . . . . . . . . . . 43
7.2 How to Build SOAP/XML Web Services . . . . . . . . . . . . . . . . . . . . . . . 43
7.2.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.2.2 MSVC++ Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7.2.3 How to Create a Stand-Alone Server . . . . . . . . . . . . . . . . . . . . . 47
7.2.4 How to Create a Multi-Threaded Stand-Alone Service . . . . . . . . . . . 48
7.2.5 How to Pass Application Data to Service Methods . . . . . . . . . . . . . 54
7.2.6 Web Service Implementation Aspects . . . . . . . . . . . . . . . . . . . . . 55
7.2.7 How to Generate C++ Server Object Classes . . . . . . . . . . . . . . . . 55
7.2.8 How to Chain C++ Server Classes to Accept Messages on the Same Port 57
7.2.9 How to Generate WSDL Service Descriptions . . . . . . . . . . . . . . . . 59
7.2.10 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
7.2.11 How to Use Client Functionalities Within a Service . . . . . . . . . . . . . 62
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
7.5.1 Mapping XML Schema to C/C++ with wsdl2h . . . . . . . . . . . . . . . 66
7.5.2 Mapping C/C++ to XML Schema with soapcpp2 . . . . . . . . . . . . . 69
7.5.3 Serializing C/C++ Data to XML . . . . . . . . . . . . . . . . . . . . . . . 70
7.5.4 Deserializing C/C++ Data from XML . . . . . . . . . . . . . . . . . . . . 76
7.5.5 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.5.6 Serializing and Deserializing Class Instances to Streams . . . . . . . . . . 81
7.5.7 How to Specify Default Values for Omitted Data . . . . . . . . . . . . . . 83
8 The wsdl2h WSDL and Schema Importer 84
8.1 wsdl2h Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
8.2 Customizing Data Bindings With The typemap.dat File . . . . . . . . . . . . . . 86
2
9 Using the soapcpp2 Compiler and Code Generator 89
9.1 soapcpp2 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
9.2 SOAP 1.1 Versus SOAP 1.2 and Dynamic Switching . . . . . . . . . . . . . . . . 92
9.3 The soapdefs.h Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
9.4 How to Build Modules and Libraries with the #module Directive . . . . . . . . . 93
9.5 How to use the #import Directive . . . . . . . . . . . . . . . . . . . . . . . . . . 94
9.6 How to Use #include and #define Directives . . . . . . . . . . . . . . . . . . . . 95
9.7 Compiling a SOAP/XML Client Application with soapcpp2 . . . . . . . . . . . . 96
9.8 Compiling a SOAP/XML Web Service with soapcpp2 . . . . . . . . . . . . . . . 96
9.9 Compiling Web Services and Clients in ANSI C . . . . . . . . . . . . . . . . . . . 97
9.10 Limitations of gSOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
9.11 Library Build Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.12 Run Time Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
9.13 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
9.13.1 Memory Allocation and Management Policies . . . . . . . . . . . . . . . . 104
9.13.2 Intra-Class Memory Management . . . . . . . . . . . . . . . . . . . . . . . 107
9.14 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9.15 Generating an Auto Test Server for Client Testing . . . . . . . . . . . . . . . . . 109
9.16 Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
10 The gSOAP Service Operation Specification Format 110
10.1 Service Operation Parameter Passing . . . . . . . . . . . . . . . . . . . . . . . . . 111
10.2 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
10.3 C/C++ Identifier Name to XML Tag Name Mapping . . . . . . . . . . . . . . . 116
10.4 Namespace Mapping Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
11 gSOAP Serialization and Deserialization Rules 122
11.1 SOAP RPC Encoding Versus Document/Literal and xsi:type Info . . . . . . . . . 123
11.2 Primitive Type Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
11.3 How to Represent Primitive C/C++ Types as XSD Types . . . . . . . . . . . . . 124
11.3.1 How to Use Multiple C/C++ Types for a Single Primitive XSD Type . . 130
11.3.2 How to use C++ Wrapper Classes to Specify Polymorphic Primitive Types130
11.3.3 XSD Schema Type Decoding Rules . . . . . . . . . . . . . . . . . . . . . . 132
11.3.4 Multi-Reference Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
11.3.5 “Smart String” Mixed-Content Decoding . . . . . . . . . . . . . . . . . . 135
11.3.6 C++ Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
11.3.7 Changing the Encoding Precision of float and double Types . . . . . . . 136
11.3.8 INF, -INF, and NaN Values of float and double Types . . . . . . . . . . 137
11.4 Enumeration Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
3
11.4.1 Serialization of Symbolic Enumeration Constants . . . . . . . . . . . . . . 137
11.4.2 Encoding of Enumeration Constants . . . . . . . . . . . . . . . . . . . . . 138
11.4.3 Initialized Enumeration Constants . . . . . . . . . . . . . . . . . . . . . . 139
11.4.4 How to “Reuse” Symbolic Enumeration Constants . . . . . . . . . . . . . 139
11.4.5 Boolean Enumeration Serialization for C . . . . . . . . . . . . . . . . . . . 140
11.4.6 Bitmask Enumeration Serialization . . . . . . . . . . . . . . . . . . . . . . 140
11.5 Struct Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
11.6 Class Instance Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
11.6.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
11.6.2 Initialized static const Fields . . . . . . . . . . . . . . . . . . . . . . . . 144
11.6.3 Class Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
11.6.4 Getter and Setter Methods . . . . . . . . . . . . . . . . . . . . . . . . . . 144
11.6.5 Streaming XML with Getter and Setter Methods . . . . . . . . . . . . . . 146
11.6.6 Polymorphism, Derived Classes, and Dynamic Binding . . . . . . . . . . . 146
11.6.7 XML Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.6.8 QName Attributes and Elements . . . . . . . . . . . . . . . . . . . . . . . 151
11.7 Union Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
11.8 Serializing Pointer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
11.8.1 Multi-Referenced Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.8.2 NULL Pointers and Nil Elements . . . . . . . . . . . . . . . . . . . . . . . 155
11.9 Void Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.10Fixed-Size Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.11Dynamic Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.11.1 SOAP Array Bounds Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 158
11.11.2 One-Dimensional Dynamic SOAP Arrays . . . . . . . . . . . . . . . . . . 158
11.11.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
11.11.4 One-Dimensional Dynamic SOAP Arrays With Non-Zero Offset . . . . . . 160
11.11.5 Nested One-Dimensional Dynamic SOAP Arrays . . . . . . . . . . . . . . 162
11.11.6 Multi-Dimensional Dynamic SOAP Arrays . . . . . . . . . . . . . . . . . 162
11.11.7 Encoding XML Generics Containing Dynamic Arrays . . . . . . . . . . . 163
11.11.8 STL Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
11.11.9 Polymorphic Dynamic Arrays and Lists . . . . . . . . . . . . . . . . . . . 168
11.11.10How to Change the Tag Names of the Elements of a SOAP Array or List 169
11.12Base64Binary XML Schema Type Encoding . . . . . . . . . . . . . . . . . . . . . 169
11.13hexBinary XML Schema Type Encoding . . . . . . . . . . . . . . . . . . . . . . . 172
11.14Literal XML Encoding Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
11.14.1 Serializing and Deserializing Mixed Content XML With Strings . . . . . . 174
4
12 SOAP Fault Processing 176
13 SOAP Header Processing 178
14 MIME Attachments 180
14.1 Sending a Collection of MIME Attachments (SwA) . . . . . . . . . . . . . . . . . 180
14.2 Retrieving a Collection of MIME Attachments (SwA) . . . . . . . . . . . . . . . 183
15 DIME Attachments 183
15.1 Sending a Collection of DIME Attachments . . . . . . . . . . . . . . . . . . . . . 184
15.2 Retrieving a Collection of DIME Attachments . . . . . . . . . . . . . . . . . . . . 184
15.3 Serializing Binary Data in DIME . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
15.4 Streaming DIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
15.5 Streaming Chunked DIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
15.6 WSDL Bindings for DIME Attachments . . . . . . . . . . . . . . . . . . . . . . . 192
16 MTOM Attachments 192
16.1 Generating MultipartRelated MIME Attachment Bindings in WSDL . . . . . . . 194
16.2 Sending and Receiving MTOM Attachments . . . . . . . . . . . . . . . . . . . . . 194
16.3 Streaming MTOM/MIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
16.4 Redirecting Inbound MTOM/MIME Streams Based on SOAP Body Content . . 200
16.5 Streaming Chunked MTOM/MIME . . . . . . . . . . . . . . . . . . . . . . . . . 201
17 XML Validation 202
17.1 Occurrence Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
17.1.1 Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
17.1.2 Elements with minOccurs and maxOccurs Restrictions . . . . . . . . . . . 203
17.1.3 Required and Prohibited Attributes . . . . . . . . . . . . . . . . . . . . . 203
17.2 Value Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
17.2.1 Data Length Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
17.2.2 Value Range Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
17.2.3 Pattern Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
17.3 Element and Attribute Qualified/Unqualified Forms . . . . . . . . . . . . . . . . 206
18 SOAP/XML Over UDP 208
18.1 Using WS-Addressing with SOAP-over-UDP . . . . . . . . . . . . . . . . . . . . 209
18.2 Client-side One-way Unicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
18.3 Client-side One-way Multicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
18.4 Client-side Request-Response Unicast . . . . . . . . . . . . . . . . . . . . . . . . 211
18.5 Client-side Request-Response Multicast . . . . . . . . . . . . . . . . . . . . . . . 211
18.6 SOAP-over-UDP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
18.7 SOAP-over-UDP Multicast Receiving Server . . . . . . . . . . . . . . . . . . . . . 214
5
