1================================================================================ 2 3Thanks for using gSOAP! 4 5The gSOAP toolkit provides a cross-platform software development toolkit for C 6and C++ server and client Web service applications, and simplifies the overall 7use of XML in any type of application. The toolkit supports SOAP 1.1/1.2 RPC 8encoding and document/literal styles, WSDL 1.1, MTOM/MIME/DIME attachments 9(streaming), SOAP-over-UDP, request-response and one-way messaging. The toolkit 10also supports WS-Addressing and WS-Security, with several other WS-* available 11or under development. See the official open-source gSOAP website 12http://gsoap2.sourceforge.net for project status and latest news. 13 14* The gSOAP 'soapcpp2' compiler and 'stdsoap2' runtime are stable since 15 version release 2.1.3. 16 17* The gSOAP 'wsdl2h' WSDL parser is stable since wsdl2h version release 1.1.0. 18 The WSDL parser fully supports WSDL 1.1 and XML schemas. 19 20The software is provided "as is", without any warranty. However, gSOAP 21has received a lot of support from users and has been extensively tested 22in the real world. We also continue to improve gSOAP and add new features. 23 24================================================================================ 25WHAT'S COOL? 26================================================================================ 27 28The gSOAP WSDL parser 'wsdl2h' is a gSOAP application itself, which 29demonstrates the capabilities of the generic XML handling by the toolkit to 30parse WSDL, XML schemas, and SOAP/XML. 31 32The gSOAP toolkit supports streaming technologies to expedite SOAP/XML and 33MTOM/MIME attachment transfers of potentially unlimited data lengths. 34 35The gSOAP toolkit is the only toolkit that supports the serialization of native 36C and C++ data types directly in XML. You can use it to export and import your 37application data in XML without having to write wrapper routines. 38 39The gSOAP toolkit ensures as small memory footprint. XML is a processed as a 40transient format and not buffered. Many optimizations have been applied to 41reduce resource requirements and to expedite XML parsing. 42 43The gSOAP toolkit provides stand-alone HTTP(S) web server functionality as well 44as Apache mod and IIS hooks. Also CGI and FastCGI is possible. A web server 45example demonstrating the stand-alone functionality is included in the package. 46 47================================================================================ 48PACKAGE 49================================================================================ 50 51This distribution package contains platform-independent source code. Pre-built 52'soapcpp2' and 'wsdl2h' binaries are included for the following platforms: 53 54 * Win32 i386 compatible 55 * Linux i386 compatible 56 * MAC OS X universal 57 58The binaries are located in 'gsoap/bin'. 59 60Important: these 'wsdl2h' binaries use the default configuration without SSL 61support (no HTTPS site access). 62 63To configure and build the toolkit binaries and libraries, please see the 64installation instructions in the 'INSTALLATION' section below. 65 66================================================================================ 67GETTING STARTED 68================================================================================ 69 70The gSOAP WSDL parser 'wsdl2h' converts WSDL into a gSOAP header file for 71processing with the gSOAP stub compiler 'soapcpp2' to generate XML 72serialization, stubs, and skeletons code to build Web services applications. 73Use the WSDL parser 'wsdl2h' followed by 'soapcpp2' to translate an entire set 74of WSDL and XML schemas into representative C or C++ data structures and 75associated XML parsers. You can also use the gSOAP compiler 'soapcpp2' directly 76on existing C/C++ data structure declarations to create XML serialization 77routines for these types to simplify the storage of data in XML. 78 79Example translation of WSDL to code in two steps: 80 81 $ wsdl2h -s -o calc.h http://www.cs.fsu.edu/~engelen/calc.wsdl 82 $ soapcpp2 calc.h 83 84The 'calc.h' header file contains the services and XML schema types represented 85in C/C++, together with other useful information copied from the WSDL related 86to the service. Run Doxygen on it to generate a nice set of pages. 87 88Do not include the wsdl2h-generated 'calc.h' header file directly into your 89code (the declarations are replicated in the generated code). The header file 90is processed by the gSOAP stub compiler 'soapcpp2' to generate the following 91files for your project: 92 93 soapClient.cpp client-side stub routines for service invocation 94 soapServer.cpp server-side skeleton routines for server development 95 soapC.cpp C/C++ parameter marshalling code 96 calc.nsmap An XML-to-C/C++ namespare mapping table 97 98To compile a client, all you need to do is to compile and link 'soapC.cpp', 99'soapClient.cpp', and 'stdsoap2.cpp' (or the installed libgsoap++, see 100INSTALLATION below) with your code. In your source code, add: 101 102 #include "soapH.h" 103 #include "calc.nsmap" 104 105This imports all soapcpp-generated definitions and the namespace mapping table. 106 107To develop a C++ client application based on proxies, use 'soapcpp2' option -i: 108 109 $ wsdl2h -s -o calc.h http://www.cs.fsu.edu/~engelen/calc.wsdl 110 $ soapcpp2 -i calc.h 111 112This generates 'soapcalcProxy.h' and 'soapcalcProxy.cpp' with a calcProxy 113class you can use to invoke the service. For example: 114 115 #include "soapcalcProxy.h" 116 #include "calc.nsmap" 117 main() 118 { calcProxy service; 119 double result; 120 if (service.add(1.0, 2.0, result) == SOAP_OK) 121 std::cout << "The sum of 1.0 and 2.0 is " << result << std::endl; 122 else 123 service.soap_stream_fault(std::cerr); 124 } 125 126Compile and link with 'soapC.cpp' and 'stdsoap2.cpp' (or -lgsoap++). 127 128To develop a C client, use 'wsdl2h' option -c to generate pure C code. 129 130There are many options that you can use depending on the need to develop C 131applications, C++ with or without STL, or C++ proxy and server objects. In 132addition, the XML schema type mapping is defined by 'typemap.dat', located in 133the 'WS' folder. The 'typemap.dat' file is used to customize the 'wsdl2h' 134output. It is important to use this file for larger projects that depend in 135WS-* protocols, such as WS-Addressing and WS-Security. 136 137More information about the 'wsdl2h' and 'soapcpp2' tools and their options can 138be found in the gSOAP documentation and the Quick How-To page on the gSOAP Web 139site, see: http://gsoap2.sourceforge.net 140 141See also the 'gsoap/wsdl/README.txt' for more details on the WSDL parser and 142installation. The 'gsoap/bin' folder includes pre-built 'soapcpp2' and 143'wsdlh2' executables for various platforms. 144 145================================================================================ 146INSTALLATION 147================================================================================ 148 149This part explains how gSOAP is build on your platform. 150 151Win32 binaries and project code is included in this package. Win32 users can 152start right away without autoconf/automake. The 'soapcpp2.exe' binary compiler 153and 'wsdl2h.exe' WSDL parser are included in 'gsoap/bin/win32', see also the 154'gsoap/VisualStudio2005' folder for the tool project files. 155 156Symbian instructions and example code is located in 'gsoap/Symbian'. 157 158Palm OS support is no longer available for this release. The latest stable 159release with Palm OS support is gSOAP 2.7.8c. 160 161To build gSOAP on your platform using autoconf/automake, please enter the 162following commands: 163 164 $ ./configure 165 $ make 166 $ make install 167 168This will install the executables and libraries on your system (and you need 169root access to do so). 170 171To configure and build the examples, use the --enable-samples option: 172 173 $ ./configure --enable-samples 174 175To configure and build the libraries in DEBUG mode, which produces 'SENT.log', 176'RECV.log' and 'TEST.log' files for message logs and gSOAP engine event logs, 177use: 178 179 $ ./configure --enable-debug 180 181If you want to install the executables in your local folder, enter: 182 183 $ ./configure 184 $ make 185 $ make install exec_prefix=$HOME 186 187To build your projects, you need the following executables: 188 189 soapcpp2 the gSOAP stub/skeleton compiler 190 wsdl2h the gSOAP WSDL parser 191 192These are created after 'make' in 'gsoap/src' and 'gsoap/wsdl'. Note that 193pre-built executables for select platforms can be found in 'gsoap/bin'. 194 195You also need the following libraries (build from stdsoap2.c[pp]): 196 197 libgsoap++.a C++ runtime 198 libgsoapck++.a C++ runtime with HTTP cookie support 199 libgsoapssl++.a C++ runtime with cookies, zlib, and SSL 200 libgsoap.a C runtime 201 libgsoapck.a C runtime with HTTP cookie support 202 libgsoapssl.a C runtime with cookies, zlib, and SSL 203 204This version of gSOAP requires SSL support with OpenSSL 0.9.6 or later. 205 206Alternatively, you can use the stdsoap2.c[pp] source code to build your project 207instead of the libraries (libraries are all derived from stdsoap2.c[pp]). See 208the gSOAP documentation on how to enable HTTP cookies, Zlib compression, and 209SSL support in stdsoap2.c[pp]. 210 211For developers: there is a command file ./makemake 212It can be used to generate the required ./configure script. 213This will create the Makefiles: 214 215 $ ./makemake 216 $ make 217 218You can also execute the following steps from the commandline: 219 220 $ aclocal 221 $ autoheader 222 $ automake --add-missing 223 $ autoconf 224 $ automake 225 $ ./configure --enable-samples 226 $ make 227 228If the above fails, try the following: 229 230 * remove autom4te.cache 231 * get the latest config.guess and config.sub from GNU 232 233================================================================================ 234BUILD NOTES 235================================================================================ 236 237QNX 238 239On QNX the bison.simple file is located in $QNX_HOST/usr/share/bison.simple 240Update your .profile to include: 241 242 export BISON_SIMPLE=$QNX_HOST/usr/share/bison/bison.simple 243 export BISON_HAIRY=$QNX_HOST/usr/share/bison/bison.hairy 244 245WIN32 246 247Bison 1.6 can crash on Win32 systems if YYINITDEPTH is too small Compile with 248/DYYINITDEPTH=5000 249 250================================================================================ 251CHANGELOG 252================================================================================ 253 254Visit http://www.cs.fsu.edu/~engelen/changelog.html to view the latest changes. 255 256================================================================================ 257LICENSE 258================================================================================ 259 260gSOAP is distributed with a choice of three licenses: 261 262* The gSOAP public open source license (which is based on the Mozilla public 263 license 1.1). See license.html or license.pdf for further details. 264 265* Or GPL (GNU Public License, a common open-source software license). 266 IMPORTANT: see NOTE below. 267 268* Or a proprietary software development license. 269 IMPORTANT: see NOTE below. 270 271You can choose which license applies best for your intended use. The software 272is offered under GPL conditions to enable the software to be used with open 273source GPL projects, educational use, and so on. We do not accept third-party 274GPL contributions to avoid having to fork the code base in GPL and non-GPL. 275 276This program is released under the GPL with the additional exemption that 277compiling, linking, and/or using OpenSSL is allowed. 278 279IMPORTANT NOTE: the wsdl2h parser, UDDI code, and sample applications such as 280the stand-alone web server are distributed ONLY under the GPL or the 281proprietary license. This means that commercial use of wsdl2h to generate code 282for product development, or the use of the UDDI source code, or the use of code 283from the sample Web service applications requires the proprietary software 284development license. The reason for this is that the wsdl2h tool, UDDI and some 285of the sample applications are not developed at Florida State University. 286Please contact me by email if you have any questions on licensing and software 287support: engelen@genivia.com. 288 289The parts of the code that are strictly distributed under the GPL (i.e. the 290code that is only distributed under GPL and not jointly under GPL and gSOAP 291public license) cannot be used for commercial purposes. These parts are: 292 293* The wsdl2h WSDL parser source code and the code generated by it. 294 295* The UDDI source code. 296 297* The examples included in the gSOAP distribution package 'samples' directory, 298 such as the router and webserver. 299 300For the most up-to-date information on licensing, please visit: 301 302http://www.cs.fsu.edu/~engelen/soaplicense.html 303 304Commercial license and software support for the entire software package is 305available. Please visit the following link for more information: 306 307http://www.genivia.com/Products/gsoap/contract.html 308 309================================================================================ 310COPYRIGHT 311================================================================================ 312 313gSOAP is copyrighted by Robert A. van Engelen, Genivia, Inc. 314Copyright (C) 2000-2008 Robert A. van Engelen, Genivia, Inc. 315All Rights Reserved. 316 317================================================================================ 318USE RESTRICTIONS 319================================================================================ 320 321You may not: (i) transfer rights to gSOAP or claim authorship; or (ii) remove 322any product identification, copyright, proprietary notices or labels from gSOAP. 323 324================================================================================ 325WARRANTY 326================================================================================ 327 328GENIVIA INC. EXPRESSLY DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED OR 329STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF 330MERCHANTABILITY, OF FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT OF THIRD 331PARTY INTELLECTUAL PROPERTY RIGHTS, AND ANY WARRANTY THAT MAY ARISE BY REASON 332OF TRADE USAGE, CUSTOM, OR COURSE OF DEALING. WITHOUT LIMITING THE 333FOREGOING, YOU ACKNOWLEDGE THAT THE SOFTWARE IS PROVIDED "AS IS" AND THAT 334GENIVIA INC. DO NOT WARRANT THE SOFTWARE WILL RUN UNINTERRUPTED OR ERROR FREE. 335LIMITED LIABILITY: THE ENTIRE RISK AS TO RESULTS AND PERFORMANCE OF THE 336SOFTWARE IS ASSUMED BY YOU. UNDER NO CIRCUMSTANCES WILL GENIVIA INC. BE LIABLE 337FOR ANY SPECIAL, INDIRECT, INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES OF 338ANY KIND OR NATURE WHATSOEVER, WHETHER BASED ON CONTRACT, WARRANTY, TORT 339(INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, ARISING OUT OF OR IN 340ANY WAY RELATED TO THE SOFTWARE, EVEN IF GENIVIA INC. HAS BEEN ADVISED ON THE 341POSSIBILITY OF SUCH DAMAGE OR IF SUCH DAMAGE COULD HAVE BEEN REASONABLY 342FORESEEN, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY 343EXCLUSIVE REMEDY PROVIDED. SUCH LIMITATION ON DAMAGES INCLUDES, BUT IS NOT 344LIMITED TO, DAMAGES FOR LOSS OF GOODWILL, LOST PROFITS, LOSS OF DATA OR 345SOFTWARE, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION OR IMPAIRMENT OF 346OTHER GOODS. IN NO EVENT WILL GENIVIA INC. BE LIABLE FOR THE COSTS OF 347PROCUREMENT OF SUBSTITUTE SOFTWARE OR SERVICES. YOU ACKNOWLEDGE THAT THIS 348SOFTWARE IS NOT DESIGNED FOR USE IN ON-LINE EQUIPMENT IN HAZARDOUS 349ENVIRONMENTS SUCH AS OPERATION OF NUCLEAR FACILITIES, AIRCRAFT NAVIGATION OR 350CONTROL, OR LIFE-CRITICAL APPLICATIONS. GENIVIA INC. EXPRESSLY DISCLAIM ANY 351LIABILITY RESULTING FROM USE OF THE SOFTWARE IN ANY SUCH ON-LINE EQUIPMENT IN 352HAZARDOUS ENVIRONMENTS AND ACCEPTS NO LIABILITY IN RESPECT OF ANY ACTIONS OR 353CLAIMS BASED ON THE USE OF THE SOFTWARE IN ANY SUCH ON-LINE EQUIPMENT IN 354HAZARDOUS ENVIRONMENTS BY YOU. FOR PURPOSES OF THIS PARAGRAPH, THE TERM 355"LIFE-CRITICAL APPLICATION" MEANS AN APPLICATION IN WHICH THE FUNCTIONING OR 356MALFUNCTIONING OF THE SOFTWARE MAY RESULT DIRECTLY OR INDIRECTLY IN PHYSICAL 357INJURY OR LOSS OF HUMAN LIFE. 358 359================================================================================ 360EXTERNAL THIRD-PARTY LIBRARIES 361================================================================================ 362 363The gSOAP toolkit is mostly self-contained and does not require any third-party 364software to run in a basic configuration. When compression and SSL encryption 365are required the Zlib and OpenSSL libraries must be installed. 366 367To build the gSOAP 'soapcpp2' compiler, you must have Bison and Flex installed 368or the older Yacc and Lex equivalents. Note that licensing differs for Flex 369versus Lex, and Bison versus Yacc. 370 371Win32 builds of clients and services requires winsock.dll. To do this in 372Visual C++ 6.0, go to "Project", "settings", select the "Link" tab (the 373project file needs to be selected in the file view) and add "wsock32.lib" to 374the "Object/library modules" entry. The distribution contains a Visual Studio 3752005 project example in the 'samples/calc_vs2005' folder with the necessary 376project settings to link libraries and automatically invoke to soapcpp2 377compiler as a custom build. 378 379================================================================================ 380DISCLAIMER 381================================================================================ 382 383WE TRY OUR BEST TO PROVIDE YOU WITH "REAL-WORLD" EXAMPLES BUT WE CANNOT 384GUARANTEE THAT ALL CLIENT EXAMPLES CAN CONNECT TO THIRD PARTY WEB SERVICES 385WHEN THESE SERVICES ARE DOWN OR HAVE BEEN REMOVED. 386 387================================================================================ 388