comparison GEMBASSY-1.0.3/gsoap/wsdl/README.txt @ 0:8300eb051bea draft

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