wsdl/README.txt - platform/external/gsoap - Git at Google

 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

 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 OUTPUT

 The typemap.dat file can be used to define namespace prefix and type bindings
 for the generated header files by the 'wsdl2h' tool. The typemap.dat is the
 default file processed by 'wsdl2h' to customize its output. You can use wsdl2h
 option -t to specify an alternate file.

 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 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();

 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
 -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
 -l      include license information in output
 -m      use xsd.h module to import primitive types
 -nname  use name as the base namespace prefix instead of 'ns'
 -Nname  use name as the base namespace prefix for service namespaces
 -ofile  output to file
 -p      create polymorphic types with C++ inheritance with base xsd__anyType
 -rhost:port
         connect via proxy host and port
 -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      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
 infile.wsdl infile.xsd http://www... list of input sources (if none use stdin)

 DOCUMENTATION

 See soapdoc2.pdf for documentation.

 INSTALLATION

 Type 'make' in the 'wsdl' directory to build wsdl2h. You must first install the
 gSOAP package and build the gSOAP compiler soapcpp2 to rebuild the wsdl2h WSDL
 parser.

 USING SSL FOR HTTPS TRANSFER OF WSDL FILES

 You must build the WSDL parser with 'make secure' to build an SSL-enabled
 version of wsdl2h that can access HTTPS secure sites.

 LICENSE

 The gSOAP WSDL parser 'wsdl2h' and source code are released under the GPL.
 See gpl.txt for more details. A 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-2005, Robert van Engelen, Genivia, Inc. All Rights Reserved.
	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

	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 OUTPUT

	The typemap.dat file can be used to define namespace prefix and type bindings
	for the generated header files by the 'wsdl2h' tool. The typemap.dat is the
	default file processed by 'wsdl2h' to customize its output. You can use wsdl2h
	option -t to specify an alternate file.

	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 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();

	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
	-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
	-l include license information in output
	-m use xsd.h module to import primitive types
	-nname use name as the base namespace prefix instead of 'ns'
	-Nname use name as the base namespace prefix for service namespaces
	-ofile output to file
	-p create polymorphic types with C++ inheritance with base xsd__anyType
	-rhost:port
	connect via proxy host and port
	-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 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
	infile.wsdl infile.xsd http://www... list of input sources (if none use stdin)

	DOCUMENTATION

	See soapdoc2.pdf for documentation.

	INSTALLATION

	Type 'make' in the 'wsdl' directory to build wsdl2h. You must first install the
	gSOAP package and build the gSOAP compiler soapcpp2 to rebuild the wsdl2h WSDL
	parser.

	USING SSL FOR HTTPS TRANSFER OF WSDL FILES

	You must build the WSDL parser with 'make secure' to build an SSL-enabled
	version of wsdl2h that can access HTTPS secure sites.

	LICENSE

	The gSOAP WSDL parser 'wsdl2h' and source code are released under the GPL.
	See gpl.txt for more details. A 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-2005, Robert van Engelen, Genivia, Inc. All Rights Reserved.