annotate GEMBASSY-1.0.3/gsoap/wsdl/README.txt @ 1:84a17b3fad1f draft

Uploaded
author ktnyt
date Fri, 26 Jun 2015 05:20:29 -0400
parents 8300eb051bea
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
1 The gSOAP WSDL parser 'wsdl2h'
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
2
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
3 INSTRUCTIONS
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
4
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
5 The gSOAP WSDL parser converts one or more WSDLs into a gSOAP header file for
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
6 processing with the gSOAP soapcpp2 compiler to generate client stubs/proxies
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
7 and server skeletons/objects to access services or build new services.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
8
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
9 For example:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
10
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
11 $ wsdl2h -o XMethodsQuery.h http://www.xmethods.net/wsdl/query.wsdl
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
12
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
13 Note: if an error occurs when running wsdl2h, please try again later. The
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
14 XMethods site is very popular and suffers under load. It may also be the case
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
15 that XMethods removed certain services. In that case, try another on-line WSDL.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
16
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
17 This generates the XMethodsQuery.h header file with Web service operations
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
18 and C++ data types. This header file is intended to be processed with soapcpp2
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
19 to generate the stub and/or skeleton code.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
20
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
21 You need to have stlvector.h present in the current directory (stlvector.h is
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
22 in the package) to support STL vectors. To build without STL, use option -s:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
23
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
24 $ wsdl2h -s -o XMethodsQuery.h http://www.xmethods.net/wsdl/query.wsdl
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
25
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
26 Or to build a pure C application, use option -c:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
27
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
28 $ wsdl2h -c -o XMethodsQuery.h http://www.xmethods.net/wsdl/query.wsdl
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
29
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
30 Other useful options to control the output are -e and -y (see below).
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
31
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
32 The above commands are to be followed by the soapcpp2 compilation phase:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
33
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
34 $ soapcpp2 -C XMethodsQuery.h
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
35
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
36 Where option -C indicates client-side only files (soapcpp2 generates both
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
37 client and server stubs and skeletons by default).
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
38
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
39 The generated XMethodsQuery.h includes the definitions of data types and
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
40 service operations of the XMethods Query Web service. To develop a C++ client
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
41 application, you can use the generated 'soapXMethodsQuerySoapProxy' class and
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
42 'XMethodsQuerySoap.nsmap' XML namespace table to access the Web service. Both
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
43 need to be '#include'd in your source. Then compile and link the soapC.cpp,
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
44 soapClient.cpp, and stdsoap2.cpp sources to complete the build. More
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
45 information on this process can be found in the gSOAP documentation.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
46
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
47 When parsing a WSDL, the output file name is the WSDL input file name with
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
48 extension '.h' instead of '.wsdl'. When an input file is absent or a WSDL file
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
49 from a Web location is accessed, the header output will be produced on the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
50 standard output. Input may also consist of schema files, which is useful when
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
51 you to need to generate code for serializing schema instances.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
52
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
53 USING A TYPEMAP FILE TO CONTROL THE INPUT AND OUTPUT
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
54
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
55 The typemap.dat is the default file processed by 'wsdl2h' to customize the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
56 generated header file output. The default typemap.dat file is located in the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
57 'WS' directory. Use wsdl2h option -t to specify an alternate file.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
58
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
59 The typemap.dat file can be used to define namespace prefix and type bindings
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
60 for the generated header files by the 'wsdl2h' tool. XML namespace prefix
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
61 bindings can be provided to override the default choice of the ns1, ns2, ...
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
62 prefixes generated by 'wsdl2h'. It is highly recommended to provide namespace
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
63 prefixes for your project's XML namespaces. In this way, changes to the WSDL
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
64 (or newer releases of wsdl2h) will have a minimal impact on coding.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
65
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
66 Bindings for namespace prefixes in typemap.dat are of the form:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
67 prefix = "URI"
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
68
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
69 For example, to bind the 'google' prefix to the Google API's namespace:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
70 google = "urn:GoogleSearch"
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
71
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
72 Type bindings can by provided to bind XML schema types to C/C++ types for your
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
73 project.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
74
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
75 Type bindings are of the form:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
76 prefix__type = declaration | use | ptr-use
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
77 where 'declaration' introduces the type in the header file, 'use' specifies how
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
78 the type is used directly, 'ptr-use' specifies how the type is used as a
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
79 pointer type.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
80
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
81 For example:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
82 xsd__string = | char* | char*
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
83 After enabling this line, all XSD strings will be mapped to char* and since
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
84 char* is already a pointer type, the 'ptr-use' part is the same as 'use' part.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
85 Note that the 'declaration' part is empty in these cases.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
86
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
87 Member data and functions can be provided to extend a generated struct or
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
88 class.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
89
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
90 Class and struct extensions are of the form:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
91 prefix__type = $ member-declaration
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
92
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
93 For example, to add a constructor and destructor to class myns__record:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
94 myns__record = $ myns__record();
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
95 myns__record = $ ~myns__record();
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
96
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
97 To specify a set of input files in typemap.dat for wsdl2h to process, use '<':
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
98 < infile1.wsdl
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
99 < infile2.xsd
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
100 < http://www.example.com/example.wsdl
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
101
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
102 To specify the default output file, use '>', for example:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
103 > example.h
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
104
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
105 Any other material to be included in the generated header file can be provided
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
106 by enclosing the text within brackets [ and ]. Brackets MUST appear at the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
107 start of a new line.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
108
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
109 For example, to include a note:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
110 [
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
111 // TODO: Don't forget to bind the namespace prefixes!
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
112 ]
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
113 This comment appears as the first line in the generated header file.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
114
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
115 INPUT FORMATS
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
116
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
117 wsdl2h reads from standard input or the files provided at the command line:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
118
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
119 wsdl2h [options] [-o outfile.h] [infile1.wsdl infile2.wsdl infile3.xsd ... ]
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
120
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
121 Valid input file formats are .wsdl and .xsd (schema) files.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
122
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
123 Multiple wsdl and schema files can be given, which results in a consolidated
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
124 header file with all definitions combined.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
125
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
126 OUTPUT FORMAT
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
127
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
128 The output file is a gSOAP-formatted header file. The header file syntax is
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
129 augmented with annotations reflecting WSDL and schema-specific bindings and
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
130 validation constraints.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
131
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
132 We suggest the use of Doxygen (www.doxygen.org) to produce documented for the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
133 generated header file. However, we STRONGLY recommend user to inspect the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
134 generated header file first for warnings and other annotations (which do not
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
135 appear in Doxygen's output) indicating potential problems.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
136
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
137 Note that Doxygen's license model does not infinge on your ownership of the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
138 generated gSOAP source code output when you purchased a commercial license.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
139
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
140 COMMAND LINE OPTIONS
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
141
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
142 -a generate indexed struct names for local elements with anonymous types
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
143 -b bi-directional operations to serve one-way response messages (duplex)
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
144 -c generate C source code
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
145 -d use DOM to populate xs:any and xsd:anyType elements
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
146 -e don't qualify enum names
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
147 -f generate flat C++ class hierarchy
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
148 -g generate global top-level element declarations
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
149 -h display help info
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
150 -Ipath use path to find files
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
151 -i don't import (advanced option)
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
152 -j don't generate SOAP_ENV__Header and SOAP_ENV__Detail definitions
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
153 -k don't generate SOAP_ENV__Header mustUnderstand qualifiers
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
154 -l include license information in output
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
155 -m use xsd.h module to import primitive types
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
156 -Nname use name for service prefixes to produce a service for each binding
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
157 -nname use name as the base namespace prefix instead of 'ns'
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
158 -ofile output to file
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
159 -P don't create polymorphic types with C++ inheritance from xsd__anyType
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
160 -p create polymorphic types with C++ inheritance from base xsd__anyType
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
161 -qname use name for the C++ namespace for all service declarations
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
162 -rhost[:port[:uid:pwd]]
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
163 connect via proxy host, port, and proxy credentials
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
164 -r:uid:pwd
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
165 connect with authentication credentials (digest auth requires SSL)
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
166 -R generate REST operations for REST bindings in the WSDL
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
167 -s don't generate STL code (no std::string and no std::vector)
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
168 -tfile use type map file instead of the default file typemap.dat
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
169 -u don't generate unions
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
170 -v verbose output
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
171 -W suppress warnings
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
172 -w always wrap response parameters in a response struct (<=1.1.4 behavior)
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
173 -x don't generate _XML any/anyAttribute extensibility elements
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
174 -y generate typedef synonyms for structs and enums
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
175 -z1 compatibility with 2.7.6e: generate pointer-based arrays
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
176 -z2 compatibility with 2.7.15: qualify element/attribute referenced members
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
177 -z3 compatibility with 2.7.16 to 2.8.7: qualify element/attribute references
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
178 -z4 compatibility up to 2.8.11: don't generate union structs in std::vector
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
179 -z5 compatibility up to 2.8.15
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
180 -_ don't generate _USCORE (replace with UNICODE _x005f)
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
181 infile.wsdl infile.xsd http://www... list of input sources (if none use stdin)
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
182
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
183 DOCUMENTATION
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
184
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
185 See soapdoc2.pdf for documentation.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
186
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
187 INSTALLATION
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
188
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
189 Use './configure' and 'make' in the root directory, as explained in the
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
190 installation instructions.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
191
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
192 To build 'wsdl2h' when autoconf/automake fail, use:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
193
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
194 make -f MakefileManual
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
195
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
196 ENABLING HTTPS SSL/TLS CONNECTIVITY AND HTTP DIGEST AUTHENTICATION
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
197
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
198 To build 'wsdl2h' with secure features, use:
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
199
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
200 make -f MakefileManual secure
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
201
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
202 If you don't have OpenSSL installed, you cannot build an SSL-secure version of
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
203 wsdl2h. In that case we recommend downloading the WSDL and schema files for
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
204 processing with the non-SSL-enabled wsdl2h tool.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
205
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
206 LICENSE
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
207
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
208 The gSOAP WSDL parser 'wsdl2h' and source code are released under GPL or
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
209 a commercial license. The commercial license is available from Genivia.
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
210 Please visit http://genivia.com/Products/gsoap/contract.html
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
211
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
212 COPYRIGHT NOTICE
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
213
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
214 gSOAP XML Web services tools
8300eb051bea Initial upload
ktnyt
parents:
diff changeset
215 Copyright (C) 2000-2013, Robert van Engelen, Genivia, Inc. All Rights Reserved.