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
-c++    generate C++ source code (default)
-c++11  generate C++11 source code
-D      make attribute members with default/fixed values optional with pointers
-d      use DOM to populate xs:any and xsd:anyType elements
-e      don't qualify enum names
-F      add transient members to structs to simulate struct-type derivation in C
-f      generate flat C++ class hierarchy by removing inheritance
-g      generate global top-level element and attribute declarations
-h      display help info and exit
-Ipath  use path to locate WSDL and XSD 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      generate less documentation by removing generic @note comments
-l      display license information
-M      suppress error "must understand element with wsdl:required='true'"
-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'
-O1     optimize by omitting duplicate choice/sequence members
-O2     optimize -O1 and omit unused schema types (unreachable from roots)
-O3     optimize -O2 and omit unused schema root attributes
-O4     optimize -O3 and omit unused schema root elements (use only with WSDLs)
-Ow2    optimize -O2 while retaining all derived types of used base types
-Ow3    optimize -O3 while retaining all derived types of used base types
-Ow4    optimize -O4 while retaining all derived types of used base types
-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
-Q      make xsd__anySimpleType equal to xsd__anyType to use as the base type
-qname  use name for the C++ namespace for all service declarations
-R      generate REST operations for REST bindings specified in a WSDL
-rhost[:port[:uid:pwd]]
        connect via proxy host, port, and proxy credentials uid and pwd
-r:uid:pwd
        connect with authentication credentials uid and pwd
-R      generate REST operations for REST bindings in the WSDL
-Sname  use name instead of 'soap' for the C++ class member with soap context
-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      display the current version and exit
-v      verbose output
-W      suppress warnings
-w      always wrap response parameters in a response struct (<=1.1.4 behavior)
-X      don't qualify part names to disambiguate doc/lit wrapped patterns
-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 include minor improvements
-z6     compatibility up to 2.8.17: don't include minor improvements
-z7     compatibility up to 2.8.59: don't generate std::vector of class of union
-z8     compatibility up to 2.8.74: don't gen quals for doc/lit wrapped patterns
-z9     compatibility up to 2.8.93: always qualify element/attribute refs
-z10    compatibility up to 2.8.96: gen quals even when defined w/o namespace
-_      don't generate _USCORE (replace with Unicode code point _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.  This builds 'wsdl2h' with all features enabled.

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

	make -f MakefileManual

To build 'wsdl2h' with secure features when `./configure' and 'make' fail, 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.

A NOTE ON HEAP MEMORY USAGE

Parts of the wsdl2h tool allocate heap memory during its execution to maintain
critical state information during its execution.  No attempt is made to release
this memory before the program terminates.

LICENSE

The gSOAP WSDL parser 'wsdl2h' and source code are released under GPLv2 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-2023, Robert van Engelen, Genivia, Inc. All Rights Reserved.
