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

Initial upload

The gSOAP WSDL parser 'wsdl2h'

INSTRUCTIONS

The gSOAP WSDL parser converts one or more WSDLs into a gSOAP header file for
processing with the gSOAP soapcpp2 compiler to generate client stubs/proxies
and server skeletons/objects to access services or build new services.

For example:

$ wsdl2h -o XMethodsQuery.h http://www.xmethods.net/wsdl/query.wsdl

Note: if an error occurs when running wsdl2h, please try again later. The
XMethods site is very popular and suffers under load. It may also be the case
that XMethods removed certain services. In that case, try another on-line WSDL.

This generates the XMethodsQuery.h header file with Web service operations
and C++ data types. This header file is intended to be processed with soapcpp2
to generate the stub and/or skeleton code.

You need to have stlvector.h present in the current directory (stlvector.h is
in the package) to support STL vectors. To build without STL, use option -s:

$ wsdl2h -s -o XMethodsQuery.h http://www.xmethods.net/wsdl/query.wsdl

Or to build a pure C application, use option -c:

$ wsdl2h -c -o XMethodsQuery.h http://www.xmethods.net/wsdl/query.wsdl

Other useful options to control the output are -e and -y (see below).

The above commands are to be followed by the soapcpp2 compilation phase:

$ soapcpp2 -C XMethodsQuery.h

Where option -C indicates client-side only files (soapcpp2 generates both
client and server stubs and skeletons by default).

The generated XMethodsQuery.h includes the definitions of data types and
service operations of the XMethods Query Web service. To develop a C++ client
application, you can use the generated 'soapXMethodsQuerySoapProxy' class and
'XMethodsQuerySoap.nsmap' XML namespace table to access the Web service. Both
need to be '#include'd in your source. Then compile and link the soapC.cpp,
soapClient.cpp, and stdsoap2.cpp sources to complete the build. More
information on this process can be found in the gSOAP documentation.

When parsing a WSDL, the output file name is the WSDL input file name with
extension '.h' instead of '.wsdl'. When an input file is absent or a WSDL file
from a Web location is accessed, the header output will be produced on the
standard output. Input may also consist of schema files, which is useful when
you to need to generate code for serializing schema instances.

USING A TYPEMAP FILE TO CONTROL THE INPUT AND OUTPUT

The typemap.dat is the default file processed by 'wsdl2h' to customize the
generated header file output. The default typemap.dat file is located in the
'WS' directory. Use wsdl2h option -t to specify an alternate file.

The typemap.dat file can be used to define namespace prefix and type bindings
for the generated header files by the 'wsdl2h' tool. XML namespace prefix
bindings can be provided to override the default choice of the ns1, ns2, ...
prefixes generated by 'wsdl2h'. It is highly recommended to provide namespace
prefixes for your project's XML namespaces. In this way, changes to the WSDL
(or newer releases of wsdl2h) will have a minimal impact on coding.

Bindings for namespace prefixes in typemap.dat are of the form:
	prefix = "URI"

For example, to bind the 'google' prefix to the Google API's namespace:
	google = "urn:GoogleSearch"

Type bindings can by provided to bind XML schema types to C/C++ types for your
project.

Type bindings are of the form:
	prefix__type = declaration | use | ptr-use
where 'declaration' introduces the type in the header file, 'use' specifies how
the type is used directly, 'ptr-use' specifies how the type is used as a
pointer type.

For example:
	xsd__string = | char* | char*
After enabling this line, all XSD strings will be mapped to char* and since
char* is already a pointer type, the 'ptr-use' part is the same as 'use' part.
Note that the 'declaration' part is empty in these cases.

Member data and functions can be provided to extend a generated struct or
class.

Class and struct extensions are of the form:
	prefix__type = $ member-declaration

For example, to add a constructor and destructor to class myns__record:
	myns__record = $ myns__record();
	myns__record = $ ~myns__record();

To specify a set of input files in typemap.dat for wsdl2h to process, use '<':
< infile1.wsdl
< infile2.xsd
< http://www.example.com/example.wsdl

To specify the default output file, use '>', for example:
> example.h

Any other material to be included in the generated header file can be provided
by enclosing the text within brackets [ and ]. Brackets MUST appear at the
start of a new line.

For example, to include a note:
[
// TODO: Don't forget to bind the namespace prefixes!
]
This comment appears as the first line in the generated header file.

INPUT FORMATS

wsdl2h reads from standard input or the files provided at the command line:

wsdl2h [options] [-o outfile.h] [infile1.wsdl infile2.wsdl infile3.xsd ... ]

Valid input file formats are .wsdl and .xsd (schema) files.

Multiple wsdl and schema files can be given, which results in a consolidated
header file with all definitions combined.

OUTPUT FORMAT

The output file is a gSOAP-formatted header file. The header file syntax is
augmented with annotations reflecting WSDL and schema-specific bindings and
validation constraints.

We suggest the use of Doxygen (www.doxygen.org) to produce documented for the
generated header file. However, we STRONGLY recommend user to inspect the
generated header file first for warnings and other annotations (which do not
appear in Doxygen's output) indicating potential problems.

Note that Doxygen's license model does not infinge on your ownership of the
generated gSOAP source code output when you purchased a commercial license.

COMMAND LINE OPTIONS

-a      generate indexed struct names for local elements with anonymous types
-b	bi-directional operations to serve one-way response messages (duplex)
-c      generate C source code
-d      use DOM to populate xs:any and xsd:anyType elements
-e      don't qualify enum names
-f      generate flat C++ class hierarchy
-g      generate global top-level element declarations
-h      display help info
-Ipath  use path to find files
-i      don't import (advanced option)
-j	don't generate SOAP_ENV__Header and SOAP_ENV__Detail definitions
-k	don't generate SOAP_ENV__Header mustUnderstand qualifiers
-l      include license information in output
-m      use xsd.h module to import primitive types
-Nname  use name for service prefixes to produce a service for each binding
-nname  use name as the base namespace prefix instead of 'ns'
-ofile  output to file
-P      don't create polymorphic types with C++ inheritance from xsd__anyType
-p      create polymorphic types with C++ inheritance from base xsd__anyType
-qname  use name for the C++ namespace for all service declarations
-rhost[:port[:uid:pwd]]
        connect via proxy host, port, and proxy credentials
-r:uid:pwd
        connect with authentication credentials (digest auth requires SSL)
-R      generate REST operations for REST bindings in the WSDL
-s      don't generate STL code (no std::string and no std::vector)
-tfile  use type map file instead of the default file typemap.dat
-u      don't generate unions
-v      verbose output
-W      suppress warnings
-w      always wrap response parameters in a response struct (<=1.1.4 behavior)
-x      don't generate _XML any/anyAttribute extensibility elements
-y      generate typedef synonyms for structs and enums
-z1     compatibility with 2.7.6e: generate pointer-based arrays
-z2     compatibility with 2.7.15: qualify element/attribute referenced members
-z3     compatibility with 2.7.16 to 2.8.7: qualify element/attribute references
-z4     compatibility up to 2.8.11: don't generate union structs in std::vector
-z5     compatibility up to 2.8.15
-_      don't generate _USCORE (replace with UNICODE _x005f)
infile.wsdl infile.xsd http://www... list of input sources (if none use stdin)

DOCUMENTATION

See soapdoc2.pdf for documentation.

INSTALLATION

Use './configure' and 'make' in the root directory, as explained in the 
installation instructions.

To build 'wsdl2h' when autoconf/automake fail, use:

	make -f MakefileManual

ENABLING HTTPS SSL/TLS CONNECTIVITY AND HTTP DIGEST AUTHENTICATION

To build 'wsdl2h' with secure features, use:

	make -f MakefileManual secure

If you don't have OpenSSL installed, you cannot build an SSL-secure version of
wsdl2h. In that case we recommend downloading the WSDL and schema files for
processing with the non-SSL-enabled wsdl2h tool.

LICENSE

The gSOAP WSDL parser 'wsdl2h' and source code are released under GPL or
a commercial license. The commercial license is available from Genivia.
Please visit http://genivia.com/Products/gsoap/contract.html

COPYRIGHT NOTICE

gSOAP XML Web services tools
Copyright (C) 2000-2013, Robert van Engelen, Genivia, Inc. All Rights Reserved.