gsoap 2.7.9e user guide

gSOAP 2.7.9 User Guide Robert van Engelen Florida State University and Genivia, Inc. engelen@genivia.com & engelen@acm.org April 1, 2007 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 14 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 17 7 Quick User Guide 18 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 7.1.4 How to Generate C++ Client Proxy Classes . . . . . . . . . . . . . . . . . 26 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 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 . . . . . . . . . 56 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 . . . . . . . . . . . . . . . . . . . . . . . 86 8.14 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 8.15 Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 9 The gSOAP Remote Method Specification Format 89 9.1 Remote Method Parameter Passing . . . . . . . . . . . . . . . . . . . . . . . . . . 90 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 98 10.1 SOAP RPC Encoding Versus Document/Literal and xsi:type Info . . . . . . . . . 98 10.2 Primitive Type Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 10.3 How to Encode and Decode Primitive Types as XSD Types . . . . . . . . . . . . 99 10.3.1 How to Use Multiple C/C++ Types for a Single Primitive XSD Type . . 106 10.3.2 How to use Wrapper Classes to Specify Polymorphic Primitive Types . . 106 10.3.3 XSD Schema Type Decoding Rules . . . . . . . . . . . . . . . . . . . . . . 108 10.3.4 Multi-Reference Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 10.3.5 “Smart String” Mixed-Content Decoding . . . . . . . . . . . . . . . . . . 111 10.3.6 STL Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 10.3.7 Changing the Encoding Precision of float and double Types . . . . . . . 112 10.3.8 INF, -INF, and NaN Values of float and double Types . . . . . . . . . . 113 10.4 Enumeration Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 10.4.1 Serialization of Symbolic Enumeration Constants . . . . . . . . . . . . . . 113 10.4.2 Encoding of Enumeration Constants . . . . . . . . . . . . . . . . . . . . . 114 10.4.3 Initialized Enumeration Constants . . . . . . . . . . . . . . . . . . . . . . 115 10.4.4 How to “Reuse” Symbolic Enumeration Constants . . . . . . . . . . . . . 115 10.4.5 Boolean Enumeration Serialization for C . . . . . . . . . . . . . . . . . . . 116 10.4.6 Bitmask Enumeration Serialization . . . . . . . . . . . . . . . . . . . . . . 116 10.5 Struct Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 10.6 Class Instance Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 3 10.6.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 10.6.2 Initialized static const Fields . . . . . . . . . . . . . . . . . . . . . . . . 119 10.6.3 Class Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 10.6.4 Getter and Setter Methods . . . . . . . . . . . . . . . . . . . . . . . . . . 120 10.6.5 Streaming XML with Getter and Setter Methods . . . . . . . . . . . . . . 121 10.6.6 Polymorphism, Derived Classes, and Dynamic Binding . . . . . . . . . . . 122 10.6.7 XML Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 10.6.8 QName Attributes and Elements . . . . . . . . . . . . . . . . . . . . . . . 127 10.7 Union Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 10.8 Serializing Pointer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 10.8.1 Multi-Referenced Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 10.8.2 NULL Pointers and Nil Elements . . . . . . . . . . . . . . . . . . . . . . . 130 10.9 Void Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 10.10Fixed-Size Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 10.11Dynamic Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 10.11.1SOAP Array Bounds Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 133 10.11.2One-Dimensional Dynamic Arrays . . . . . . . . . . . . . . . . . . . . . . 133 10.11.3Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 10.11.4One-Dimensional Dynamic Arrays With Non-Zero Offset . . . . . . . . . 136 10.11.5Nested One-Dimensional Dynamic Arrays . . . . . . . . . . . . . . . . . . 137 10.11.6Multi-Dimensional Dynamic Arrays . . . . . . . . . . . . . . . . . . . . . 138 10.11.7Encoding XML Generics Containing Dynamic Arrays . . . . . . . . . . . 139 10.11.8STL Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 10.11.9Polymorphic Dynamic Arrays and Lists . . . . . . . . . . . . . . . . . . . 143 10.11.10How to Change the Tag Names of the Elements of a SOAP Array or List 143 10.12Base64Binary XML Schema Type Encoding . . . . . . . . . . . . . . . . . . . . . 144 10.13hexBinary XML Schema Type Encoding . . . . . . . . . . . . . . . . . . . . . . . 146 10.14Literal XML Encoding Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 10.14.1Serializing and Deserializing Mixed Content XML With Strings . . . . . . 148 11 SOAP Fault Processing 150 12 SOAP Header Processing 152 13 MIME Attachments 154 13.1 Sending a Collection of MIME Attachments (SwA) . . . . . . . . . . . . . . . . . 155 13.2 Retrieving a Collection of MIME Attachments (SwA) . . . . . . . . . . . . . . . 157 4 14 DIME Attachments 158 14.1 Sending a Collection of DIME Attachments . . . . . . . . . . . . . . . . . . . . . 158 14.2 Retrieving a Collection of DIME Attachments . . . . . . . . . . . . . . . . . . . . 158 14.3 Serializing Binary Data in DIME . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 14.4 Streaming DIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 14.5 Streaming Chunked DIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 14.6 WSDL Bindings for DIME Attachments . . . . . . . . . . . . . . . . . . . . . . . 166 15 MTOM Attachments 166 15.1 Generating MultipartRelated MIME Attachment Bindings in WSDL . . . . . . . 168 15.2 Sending and Receiving MTOM Attachments . . . . . . . . . . . . . . . . . . . . . 168 15.3 Streaming MTOM/MIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 15.4 Redirecting Inbound MTOM/MIME Streams Based on SOAP Body Content . . 174 15.5 Streaming Chunked MTOM/MIME 16 XML Validation . . . . . . . . . . . . . . . . . . . . . . . . . 175 176 16.1 Occurrence Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 16.1.1 Elements with minOccurs and maxOccurs Restrictions . . . . . . . . . . . 176 16.1.2 Required and Prohibited Attributes . . . . . . . . . . . . . . . . . . . . . 177 16.1.3 Data Length Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 16.2 Other Constraints 17 SOAP-over-UDP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 179 17.1 Using WS-Addressing with SOAP-over-UDP . . . . . . . . . . . . . . . . . . . . 180 17.2 Client-side One-way Unicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 17.3 Client-side One-way Multicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 17.4 Client-side Request-Response Unicast . . . . . . . . . . . . . . . . . . . . . . . . 181 17.5 Client-side Request-Response Multicast . . . . . . . . . . . . . . . . . . . . . . . 182 17.6 SOAP-over-UDP Server 18 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 185 18.1 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 18.2 Customizing the WSDL and Namespace Mapping Table File Contents With gSOAP Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 18.2.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 18.3 Transient Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 18.4 Volatile Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 18.5 How to Declare User-Defined Serializers and Deserializers . . . . . . . . . . . . . 195 18.6 How to Serialize Data Without Generating XSD Type Attributes . . . . . . . . . 196 18.7 Function Callbacks for Customized I/O and HTTP Handling . . . . . . . . . . . 196 5 ... - tailieumienphi.vn