The wsdl2h tool is an advanced application that converts one or more WSDLs to C/C++. It can also be used without WSDLs to convert XML schemas (XSD files) to C/C++ to implement XML data bindings in C and C++. The creation of C and C++ applications from one of more WSDL service descriptions is a two-step process. To convert a WSDL to C++, use:
| > wsdl2h file.wsdl |
to generate a C++ header file file.h.This generated header file is a Web service specification that contains the parameter types and service function definitions in an understandable format in C++ (or ANSI C as shown below).Web service operations are represented as function prototypes. Schema types arerepresented by semantically equivalent C/C++ types that are convenient andnatural to use in a C/C++ application. The generated header file also containsvarious annotations related to the Web service properties defined in the WSDL.To generate ANSI C, use option -c:
| > wsdl2h -c file.wsdl |
Multiple WSDL specifications can be processed at once and saved to one file with the -o option:
| > wsdl2h -o file.h file1.wsdl file2.wsdl file3.wsdl |
You can retrieve WSDLs from one of more URLs:
| > wsdl2h -o file.h http://www.example.com/example.wsdl |
To convert XML schemas to C or C++ XML data binding code, use:
| > wsdl2h -o file.h file1.xsd file2.xsd file3.xsd |
The wsdl2h-generated header file file.h is processed by thesoapcpp2 tool to auto-generate the advanced data binding logic toconvert the C/C++ data to XML and vice versa at runtime for your SOAP/XMLapplication.To process a gSOAP header file file.h (generated by wsdl2h) to generate advanced XML data bindings for C++, use:
| > soapcpp2 -i -Iimport file.h |
When the header file file.h was generated for C++, then this commandgenerates a couple of C++ source files (more details will follow inSection 9) that implement XML encoders for the data binding.Option -i generates a client proxy objects and service objects to invokeand serve SOAP/XML operations, respectively. Option -Iimport sets theimport directory for imported files from the package's import, such asstlvector.h for STL vector serialization support.When the header file file.h was generated for ANSI C, then the abovecommand generates a couple of C files that implement XML encoders, client stubsfor remote invocation, and service skeletons for service operations. Consider for example the following commands to implement a c++ client of a service:
| > wsdl2h -o calc.h http://www.genivia.com/calc.wsdl ... > soapcpp2 -i -Iimport calc.h |
The first command generates calc.h from the WSDL at the specified URL.The header file is then processed by the soapcpp2 tool to generate theproxies (and service objects that we will not use) for the client application.The C++ client application uses the auto-generated soapcalcProxy.h class andcalc.nsmap XML namespace table to access the Webservice. Both need to be #include-d in your source. Then compile and linkthe soapcalcProxy.cpp, soapC.cpp and stdsoap2.cpp sources to complete the build.
The wsdl2h tool is an advanced XML data binding tool for converting WSDLsand XML schemas (XSD files) to C or C++. The tool takes WSDL and/or XSD filesor URLs and converts these to a C or C++ specification in one easy-to-readC/C++ header file. The header file is not intended to be included in yourcode directly!. It should be converted by soapcpp2 to generate the logicfor the data bindings. It can however be safely converted by a documentationtool such as Doxygen to analyze and represent the service operations and datain a convenient layout. To this end, the header file is self-explanatory.The wsdl2h tool generates only one file, the header file that includesall of the information obtained from all WSDL and schema files provided to thetool at the command-line prompt. The default output file name of wsdl2his the first WSDL/schema input file name but with extension .h instead of.wsdl (or .xsd). When an input file is absent or a WSDL file from aWeb location is accessed, the header output will be produced on the standardoutput unless option -o is used to direct the output to a file.The wsdl2h command-line options are:
|
Note: see README.txt in the wsdl directory for the latestinformation on installation and options to of the wsdl2h WSDL/schema importer.
The typemap.dat file for the wsdl2h tool is intended to customize or optimizethe type bindings by mapping schema types to C/C++ types. It contains customXML Schema to C/C++ type bindings and a few bindings are defined forconvenience.Here is an example typemap file's content:
| # This file contains custom definitions of the XML Schema types and # C/C++ types for your project, and XML namespace prefix definitions. # The wsdl2h WSDL importer consults this file to determine bindings. [ // This comment will be included in the generated .h file // You can include any additional declarations, includes, imports, etc. // within [ ] sections. The brackets MUST appear at the start of a line ] # XML namespace prefix definitions can be provided to override the # default choice of ns1, ns2, ... prefixes. For example: i = "http://www.soapinterop.org/" s = "http://www.soapinterop.org/xsd" |
Type bindings can be provided to bind XML schema types to C/C++types for your project.Type bindings have four parts:
| prefix__type = declaration | use | ptr-use |
where 'prefix__type' is the C/C++-translation of the schema type,'declaration' introduces the C/C++ type in the header file, the optional'use' specifies how the type is used directly, and the optional'ptr-use' specifies how the type is used as a pointer type.
| # Example XML Schema and C/C++ type bindings: xsd__int = | int xsd__string = | char* | char* xsd__boolean = enum xsd__boolean false_, true_ ; | enum xsd__boolean xsd__base64Binary = class xsd__base64Binary unsigned char *__ptr; int __size; ; | xsd__base64Binary | xsd__base64Binary # You can extend structs and classes with member data and functions. # For example, adding a constructor to ns__myClass:ns__myClass = $ ns__myClass(); # The general form is# class_name = $ member; |
The i and s prefixes are declared such that the header file output by the WSDL parser will use these to produce C/C++ code.XML Schema types are associated with an optional C/C++ type declaration, a use reference, and a pointer-use reference. The pointer-use reference of the xsd__byte type for example, is int* because char* is reserved for strings.When a type binding requires only the usage to be changed, thedeclaration part can be given by an elipsis ..., as in:
| prefix__type = ... | use | ptr-use |
This ensures that the wsdl2h-generated type definition is preserved,while the use and ptr-use are remapped.This method is useful to serialize dynamic types in C, where elements types intXML carry the xsi:type attribute.The following example illustrates an "any" type mapping for thens:sometype XSD type in a schema. This type will be replaced with a "any"type wrapper that supports dynamic serialization with xsi:type:
| [ struct __any { int __type; void *__item; } ] xsd__anyType = ... | struct __any | struct __any |
where __type and __item are used to (de)serialize any data type in the wrapper,including base and its derived types based on xsi:type attribuation.To support complexType extensions that are dynamically bound in C code, i.e.polymorphic types based on inheritance hierarchies, we can redeclare the basetype of a hierarchy as a wrapper type and use the __type to serializebase or derived types. One addition is needed to support base typeserialization without the use of xsi:type attributes. The absence of this attribute requires the serialization of the base type.Basically, we need to be able to both handle a base type and its extensionsas per schema extensibility. Say base type ns:base is a complexType that is extended by several other complexTypes. To implement dynamic binding in C to serialize the base type and derived types, we define:
| [ struct __ns__base { int __type; void *__item; struct ns__base *__self; } ] ns__base = ... | struct __ns__base | struct __ns__base |
The __self field refers to the element tag (basically a struct member name)to which the ns:base type is associated. So for example, we see in the soapcpp2-generated output:
| struct ns__data { ... struct __ns__base name; ... }; |
where __item represents name when the __ns__base isserialized with an xsi:type attribute, and __self representsname when the __ns__base is serialized wwithout an xsi:typeattribute. Therefore, the dynamic binding defaults to struct ns__base*__self when no dynamic type information in XML is available.Additional data and function members can be provided to extend agenerated 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(); |
Type remappings can be given to map a type to another type:
| prefix__type1 == prefix__type2 |
which replaces prefix__type1 by prefix__type2 in the wsdl2h output.For example:
| SOAP_ENC__boolean == xsd__boolean |
where SOAP_ENC__boolean is mapped to xsd__boolean, which in turn may be mapped to a C enum xsd__boolean type or C++ bool type.
The soapcpp2 compiler and code generator is invoked from the command lineand optionally takes the name of a header file as an argument or, when the filename is absent, parses the standard input:
| > soapcpp2 [aheaderfile.h] |
where aheaderfile.h is a C/C++ header file generated by wsdl2h ordeveloped manually to specify the SOAP/XML service operations as functionprototypes and the C/C++ data types to be auto-mapped to XML.The soapcpp2 tool produces C/C++ source files. These files are used toimplement SOAP/XML clients and services, and to implement the advanced XML databinding logic to convert C/C++ data into XML and vice versa.The type of files generated by soapcpp2 are:
|
Both client and service applications are developed from a header file thatspecifies the service operations. If client and service applications aredeveloped with the same header file, the applications are guaranteed to becompatible because the stub and skeleton routines use the same serializers anddeserializers to encode and decode the parameters. Note that when client andservice applications are developed together, an application developer does notneed to know the details of the internal SOAP encoding used by the client andservice.The soapClientLib.cpp and soapServerLib.cpp can be used to build (dynamic) client and server libraries. The serialization routines are local (static) to avoid link symbol conflicts. You must create a separate library for SOAP Header and Fault handling, as described in Section 19.36.The following files are part of the gSOAP package and are required to build client and service applications:
|
The soapcpp2 source-to-source compiler supports the following command-line options:
|
For example
| > soapcpp2 -cd '../projects' -pmy file.h |
Saves the sources:
| ../projects/myH.h ../projects/myC.c ../projects/myClient.c ../projects/myServer.c ../projects/myStub.h |
MS Windows users can use the usual "/" for options, for example:
| soapcpp2 /cd '..\projects' /pmy file.h |
Compiler options c, i, n, l, w can be set in the gSOAP header file using the //gsoapopt directive. For example,
| // Generate pure C and do not produce WSDL output: //gsoapopt cw int ns__myMethod(char*,char**); // takes a string and returns a string |
gSOAP supports SOAP 1.1 by default. SOAP 1.2 support is automatically turned on when the appropriate SOAP 1.2 namespace is used, which shows up inthe namespace mapping table:
| struct Namespace namespaces[] = { {"SOAP-ENV", "http://www.w3.org/2003/05/soap-envelope", ... }, {"SOAP-ENC", "http://www.w3.org/2003/05/soap-encoding, ... "}, ... } |
Normally the soapcpp2-generated namespace table allows dynamic switching between SOAP 1.1 to SOAP 1.2 by providing the SOAP 1.2 namespaceas a pattern in the third column of a namespace table:
| struct Namespace namespaces[] = { {"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/", "http://www.w3.org/*/soap-encoding"}, {"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/", "http://www.w3.org/*/soap-envelope"}, ... } |
where the "*" in the third column of the namespace URI pattern is a meta wildcard. This is used to match and accept inbound namespaces.This way, gSOAP Web services can respond to either SOAP 1.1 or SOAP 1.2 requests. gSOAP will automatically return SOAP 1.2 responses for SOAP 1.2 requests.The gSOAP soapcpp2 tool generates a .nsmap file with SOAP-ENV and SOAP-ENC namespace patterns similar to the above.Since clients issue a send first, they will always use SOAP 1.1 for requests when the namespace table is similar as shown above.Clients can accept SOAP 1.2 responses by inspecting the response message.To use SOAP 1.2 by default and allow SOAP 1.1 messages to be received, use the soapcpp2 -2 option to generate SOAP 1.2 conformant .nsmap and .wsdl files. Alternatively, add the following line to your service definitions header file (generated by wsdl2h) for soapcpp2:
| #import "import/soap12.h" |
Caution: SOAP 1.2 does not support partially transmitted arrays. So the __offset field of a dynamic array is meaningless.Caution: SOAP 1.2 requires the use of SOAP_ENV__Code, SOAP_ENV__Reason, and SOAP_ENV__Detail fieldsin a SOAP_ENV__Fault fault struct, while SOAP 1.1 uses faultcode, faultstring, and detail fields.Use soap_receiver_fault_subcode(struct soap *soap, const char *subcode, const char *faultstring, const char *detail) to set a SOAP 1.1/1.2fault at the server-side with a fault subcode (SOAP 1.2).Use soap_sender_fault_subcode(struct soap *soap, const char *subcode, const char *faultstring, const char *detail) to set a SOAP 1.1/1.2unrecoverable Bad Request fault at the server-side with a fault subcode (SOAP 1.2).
The soapdefs.h header file is included in stdsoap2.h when compiling with option -DWITH_SOAPDEFS_H:
| > c++ -DWITH_SOAPDEFS_H -c stdsoap2.cpp |
The soapdefs.h file allows users to include definitions and add includes without requiring changes to stdsoap2.h.For example,
| // Contents of soapdefs.h #include < ostream > #define SOAP_BUFLEN 65536 // use large send/recv buffer |
The following header file can now refer to ostream:
| extern class ostream; // ostream can't be (de)serialized, but need to be declared to make it visible to gSOAP class ns__myClass { ... virtual void print(ostream &s) const; // need ostream here ... }; |
See also Section 19.3.
The #module directive is used to build modules. A library can be build from a module and linked with multiple Web services applications. The directive should appear at the top of the header file and has the following formats:
| #module "name" |
and
| #module "name" "fullname" |
where name must be a unique short name for the module. The name is case insensitive and MUST not exceed 4 characters in length. The fullname, when present, represents the full name of the module.The rest of the content of the header file includes type declarations and optionally the declarations of service operations and SOAP Headers/Faults. When the gSOAP soapcpp2 compiler processes the header file module, it will generate the source codes for a library. The Web services application that uses the library should use a header file that imports the module with the #import directive.For example:
| /* Contents of module.h */ #module "test" long; char*; struct ns__S { ... } |
The module.h header file declares a long, char*, and a struct ns__X. The module name is "test", so the gSOAP soapcpp2 compiler produces a testC.cpp file with the (de)serializers for these types. The testC.cpp library can be separately compiled and linked with an application that is built from a header file that imports "module.h" using #import "module.h". You should also compile testClient.cpp when you want to build a library that includes the service opertions that you defined in the module header file.There are some limitations on a sequence of module imports. A module MUST be imported into another header to use the module content and you MUST place this import statement before all other statements in the file, including other imports (except when these are also modules). It is also advised to put all basic data type definitions in the root module of a module import hierarchy, e.g. using typedef to declare XSD types (see also Section 11.3).You cannot use a module alone to build a SOAP or XML application. That is, the final gSOAP header file in the import chain SHOULD NOT be a module.When multiple modules are linked, the types that they declare MUST be declared in one module only to avoid name clashes and link errors. You cannot create two modules that share the same type declaration and link the modules. When necessary, you should consider creating a module hierarchy such that types are declared only once and by only one module when these modules must be linked.
The #import directive is used to include gSOAP header files into other gSOAP header files for processing withthe gSOAP compiler soapcpp2.The C #include directive cannot be used to include gSOAP header files.The #include directive is reserved to control the post-gSOAP compilation process, see 9.6.The #import directive is used for two purposes: you can use it to include the contents of a header file into another header file and you can use it to import a module, see 9.4.An example of the #import directive:
| #import "mydefs.gsoap" int ns__mymethod(xsd__string in, xsd__int *out); |
where "mydefs.gsoap" is a gSOAP header file that defines xsd__string and xsd__int:
| typedef char *xsd__string; typedef int xsd__int; |
When importing a module, where the module content is declared with #module, then note that this module MUST place the import statement before all other statements in the header file, including other imports (except when these are also modules).
The #include and #define directives are normally ignored by the gSOAP soapcpp2 compiler and just passed on to the generated code.Thus, the gSOAP compiler will not actually parse the contents of the header files provided by the #include directives in a header file.Instead, the #include and #define directives will be added to the generated soapH.h header file beforeany other header file is included. Therefore, #include and #define directives can be used to control the C/C++compilation process of the sources of an application. However, they have no effect on soapcpp2.The following example header file refers to ostream by including < ostream > :
| #include < ostream > #define WITH_COOKIES // use HTTP cookie support (you must compile stdsoap2.cpp with -DWITH_COOKIES) #define WITH_OPENSSL // enable HTTPS/SSL support (you must compile stdsoap2.cpp with -DWITH_OPENSSL) #define WITH_GNUTLS // enable HTTPS/SSL support (you must compile stdsoap2.cpp with -DWITH_GNUTLS) #define SOAP_DEFAULT_float FLT_NAN // use NaN instead of 0.0 extern class ostream; // ostream can't be (de)serialized, but need to be declared to make it visible to gSOAP class ns__myClass { ... virtual void print(ostream &s) const; // need ostream here ... }; |
This example also uses #define directives for various settings in the target source code.Caution: Note that the use of #define in the header file does not automatically result in compilingstdsoap2.cpp with these directives. You MUST use the -DWITH_COOKIES and -DWITH_OPENSSL (or -DWITH_GNUTLS options whencompiling stdsoap2.cpp before linking the object file with your codes. As an alternative, you can use #defineWITH_SOAPDEFS_H and put the #define directives in the soapdefs.h file.
After invoking the gSOAP soapcpp2 tool on a header file description of a service, the client application can be compiled on a Linux machine as follows:
| > c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp |
Or on a Unix machine:
| > c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp -lsocket -lxnet -lnsl |
(Depending on your system configuration, the libraries libsocket.a,libxnet.a, libnsl.a or dynamic *.so versions of those libraries are required.)The myclient.cpp file must include soapH.h and must define a global namespace mapping table. A typical client program layout with namespace mapping table is shown below:
| // Contents of file "myclient.cpp" #include "soapH.h"; ... // A service operation invocation: soap_call_some_remote_method(...); ... struct Namespace namespaces[] = { // {"ns-prefix", "ns-name"} {"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, {"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, {"xsi", "http://www.w3.org/2001/XMLSchema-instance"}, {"xsd", "http://www.w3.org/2001/XMLSchema"}, {"ns1", "urn:my-remote-method"}, {NULL, NULL} }; ... |
A mapping table is generated by the gSOAP soapcpp2 compiler that can be used in the source, see Section 7.2.9.
After invoking the gSOAP soapcpp2 tool on a header file description of the service, the server application can be compiled on a Linux machine as follows:
| > c++ -o myserver myserver.cpp stdsoap2.cpp soapC.cpp soapServer.cpp |
Or on a Unix machine:
| > c++ -o myserver myserver.cpp stdsoap2.cpp soapC.cpp soapServer.cpp -lsocket -lxnet -lnsl |
(Depending on your system configuration, the libraries libsocket.a,libxnet.a, libnsl.a or dynamic *.so versions of those libraries are required.)The myserver.cpp file must include soapH.h and must define a global namespace mapping table. A typical service program layout with namespace mapping table is shown below:
| // Contents of file "myserver.cpp" #include "soapH.h"; int main() { soap_serve(soap_new()); } ... // Implementations of the service operations as C++ functions ... struct Namespace namespaces[] = { // {"ns-prefix", "ns-name"} {"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, {"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, {"xsi", "http://www.w3.org/2001/XMLSchema-instance"}, {"xsd", "http://www.w3.org/2001/XMLSchema"}, {"ns1", "urn:my-remote-method"}, {NULL, NULL} }; ... |
When the gSOAP service is compiled and installed as a CGI application, the soap_serve function acts as a service dispatcher. It listens to standard input andinvokes the method via a skeleton routine to serve a SOAP client request. After the request is served, the response is encoded inSOAP and send to standard output. The method must be implemented in the server application and the type signature of the methodmust be identical to the service operations specified in the header file. That is, the function prototype in the header file must be avalid prototype of the method implemented as a C/C++ function.
The gSOAP soapcpp2 compiler can be used to create pure C Web services and clients. The gSOAP stub and skeleton compilersoapcpp2 generates .cpp files by default. The compiler generates .c files with the -c option.However, these files only use C syntax and data types if the headerfile input to soapcpp2 uses C syntax and data types. For example:
| > soapcpp2 -c quote.h > cc -o quote quote.c stdsoap2.c soapC.c soapClient.c |
Warnings will be issued by the compiler when C++ class declarations occur in the header file.
gSOAP is SOAP 1.1 and SOAP 1.2 compliant and supports SOAP RPC and document/literal operations.From the perspective of the C/C++ language, a few C++ language features are not supported by gSOAP and these features cannot be used in the specification of SOAP service operations.There are certain limitations for the following C++ language constructs:
The following data types require some attention to ensure they are serialized:
There are a number of programming solutions that can be adopted to circumvent these limitations. Instead of using void*, a programcan in some cases be modified to use a pointer to a known type. If the pointer is intended to point to different types of objects, a genericbase class can be declared and the pointer is declared to point to the base class. All the other types are declared to be derivedclasses of this base class. For pointers that point to a sequence of elements in memory dynamic arrays should be used instead,see 11.11.
The following macros (#defines) can be used to enable certain optional features when building the libgsoap library or when compiling and linking stdsoap2.c and stdsoap2.cpp:
|
Other compile-time flags:
|
Compile-time flags to change the default engine settings:
|
Caution: it is important that all of these macros MUST be consistently defined tocompile all sources, such as stdsoap2.cpp, soapC.cpp,soapClient.cpp, soapServer.cpp, and all application sources thatinclude stdsoap2.h or soapH.h. If the macros are not consistentlyused, the application will crash due to a mismatches in the declaration andaccess of the gSOAP context.
gSOAP provides flags to control the input and output mode settings at runtime.These flags are divided into four categories: transport (IO), content encoding(ENC), XML marshalling (XML), and C/C++ data mapping (C).Although gSOAP is fully SOAP 1.1 compliant, some SOAP implementations may havetrouble accepting multi-reference data and/or require explicit nil data sothese flags can be used to put gSOAP in "safe mode". In addition, theembedding (or inlining) of multi-reference data is adopted in the SOAP 1.2specification, which gSOAP automatically supports when handling with SOAP 1.2messages.To set and clear flags for inbound message processing use:
| soap_set_imode(soap, inflag); soap_clr_imode(soap, inflag); |
To set and clear the flags for outbound message processing use:
| soap_set_omode(soap, outflag); soap_clr_imode(soap, outflag); |
To allocate and initialize a gSOAP context with inbound and outbound flags use:
| soap_new2(soap, inflag, outflag); |
To initialize an unitialized gSOAP context with inbound and outbound flags use:
| soap_init2(soap, inflag, outflag); |
The input-mode and output-mode flags for inbound and outbound message processing are:
|
The flags can be selectively turned on/off at any time, for example whenmultiple Web services are accessed by a client that require special treatment.All flags are orthogonal, exceptSOAP_IO_FLUSH,SOAP_IO_BUFFER,SOAP_IO_STORE, andSOAP_IO_CHUNKwhich are enumerations and only one of these I/O flags can be used. Also theXML serialization flagsSOAP_XML_TREE andSOAP_XML_GRAPH should not be mixed.The flags control the inbound and outbound message transport, encoding, and(de)serialization. The following functions are used to set and reset the flagsfor input and output modes:
|
The default setting is SOAP_IO_DEFAULT for both input and output modes.For example
| struct soap soap; soap_init2(&soap, SOAP_IO_KEEPALIVE, SOAP_IO_KEEPALIVE | SOAP_ENC_ZLIB | SOAP_XML_TREE | SOAP_XML_CANONICAL); if (soap_call_ns__myMethod(&soap, ...)) ... |
sends a compressed client request with keep-alive enabled and all data serialized as canonical XML trees.In many cases, setting the input mode will have no effect, especially with HTTPtransport because gSOAP will determine the optimal input buffering and theencoding used for an inbound message. The flags that have an effect onhandling inbound messages are SOAP_IO_KEEPALIVE, SOAP_ENC_SSL(but automatic when "https:" endpoints are used or soap_ssl_accept),SOAP_C_NOIOB, SOAP_C_UTFSTRING, and SOAP_C_MBSTRING.Caution: The SOAP_XML_TREE serialization flag can be used toimprove interoperability with SOAP implementations that are not fully SOAP 1.1compliant. However, a tree serialization will duplicate data when necessaryand will crash the serializer for cyclic data structures.
Understanding gSOAP's run-time memory management is important to optimizeclient and service applications by eliminating memory leaks and/or danglingreferences.There are two forms of dynamic (heap) allocations made by gSOAP's runtime forserialization and deserialization of data. Temporary data is created by theruntime such as hash tables to keep pointer reference information forserialization and hash tables to keep XML id/href information formulti-reference object deserialization. Deserialized data is created uponreceiving SOAP messages. This data is stored on the heap and requires severalcalls to the malloc library function to allocate space for the data andnew to create class instances. All such allocations are tracked bygSOAP's runtime by linked lists for later deallocation. The linked list formalloc allocations uses some extra space in each malloced block toform a chain of pointers through the malloced blocks. A separatemalloced linked list is used to keep track of class instance allocations.If you want to preserve the deserialized data before deleting a soap context, you can assign management of the data and delegate responsibility of deletion to another soap context using soap_delegate_deletion(struct soap *soap_from, struct soap *soap_to). This moves all deserialized and temporary data to the other soap context soap_to, which will delete its data and all the delegated data it is responsible for when you call soap_destroy and soap_end. This can be particularly useful for making client calls inside a server operation, i.e. a mixed server/client. The client call inside the server operation requires a new soap context, e.g. copied from the server's with soap_copy. Before destroying the client context with soap_free, the data can be delegated to the server's context with soap_delegate_deletion. See samples/mashup/machupserver.c code for an example.Note that gSOAP does not per se enforce a deallocation policy and the user canadopt a deallocation policy that works best for a particular application. As aconsequence, deserialized data is never deallocated by the gSOAP runtime unlessthe user explicitly forces deallocation by calling functions to deallocate datacollectively or individually.The deallocation functions are:
|
Temporary data (i.e. the hash tables) are automatically removed with calls tothe soap_free_temp function which is also made by soap_end andsoap_done or when the next call to a stub or skeleton routine is made tosend a message or receive a message. Deallocation of non-class based data isstraightforward: soap_end removes all dynamically allocated deserializeddata (data allocated with soap_malloc. That is, when the client/serviceapplication does not use any class instances that are (de)marshalled, but usesstructs, arrays, etc., then calling the soap_end function is safe toremove all deserialized data. The function can be called after processing thedeserialized data of a service operation call or after a number of service operationcalls have been made. The function is also typically called aftersoap_serve, when the service finished sending the response to a clientand the deserialized client request data can be removed.Individual data objects can be unlinked from the deallocation chain ifnecessary, to prevent deallocation by the collective soap_end orsoap_destroy functions.
There are three situations to consider for memory deallocation policies for class instances:
It is advised to use pointers to class instances that are used within other structs and classes to avoid the creation of temporaryclass instances during deserialization. The problem with temporary class instances is that the destructor of the temporary may affect data used byother instances through the sharing of data parts accessed with pointers. Temporaries and even whole copies of class instancescan be created when deserializing SOAP multi-referenced objects.A dynamic array of class instances is similar: temporaries may be created to fill the array upon deserialization. To avoidproblems, use dynamic arrays of pointers to class instances. This also enables the exchange of polymorphic arrays when theelements are instances of classes in an inheritance hierarchy.In addition, allocate data and class instances with soap_malloc and soap_new_X functions (more details below).To summarize, it is advised to pass class data types by pointer to a service operation. For example:
| class X { ... }; ns__remoteMethod(X *in, ...); |
Response elements that are class data types can be passed by reference, as in:
| class X { ... }; class ns__remoteMethodResponse { ... }; ns__remoteMethod(X *in, ns__remoteMethodResponse &out); |
But dynamic arrays declared as class data types should use a pointer to a valid object that will be overwritten when thefunction is called, as in:
| typedef int xsd__int; class X { ... }; class ArrayOfint { xsd__int *__ptr; int __size; }; ns__remoteMethod(X *in, ArrayOfint *out); |
Or a reference to a valid or NULL pointer, as in:
| typedef int xsd__int; class X { ... }; class ArrayOfint { xsd__int *__ptr; int __size; }; ns__remoteMethod(X *in, ArrayOfint *&out); |
The gSOAP memory allocation functions can be used in client and/or service code to allocate temporary data that will beautomatically deallocated.These functions are:
|
The soap_new_X functions are generated by the gSOAP soapcpp2 compiler for every class X in the header file.Space allocated with soap_malloc will be released with the soap_end and soap_dealloc functions.All objects instantiated with soap_new_X(struct soap*) are removed altogether with soap_destroy(struct soap*).To remove just a single object, use soap_delete_X(struct soap*, X*).For example, the following service uses temporary data in the service operation implementation:
| int main() { ... struct soap soap; soap_init(&soap); soap_serve(&soap); soap_end(&soap); ... } |
An example service operation that allocates a temporary string is:
| int ns__itoa(struct soap *soap, int i, char **a) { *a = (char*)soap_malloc(soap, 11); sprintf(*a, "%d", i); return SOAP_OK; } |
This temporary allocation can also be used to allocate strings for the SOAP Fault data structure. For example:
| int ns__mymethod(...) { ... if (exception) { char *msg = (char*)soap_malloc(soap, 1024); // allocate temporary space for detailed message sprintf(msg, "...", ...); // produce the detailed message return soap_receiver_fault(soap, "An exception occurred", msg); // return the server-side fault } ... } |
Use soap_receiver_fault(struct soap *soap, const char *faultstring, const char *detail) to set a SOAP 1.1/1.2 fault at the server-side.Use soap_sender_fault(struct soap *soap, const char *faultstring,const char *detail) to set a SOAP 1.1/1.2 unrecoverable Bad Request faultat the server-side. Sending clients are not supposed to retry messages after aBad Request, while errors at the receiver-side indicate temporary problems.The above functions do not include a SOAP 1.2 Subcode element. To include Subcode element, use soap_receiver_fault_subcode(struct soap *soap, const char *subcode, const char *faultstring, const char *detail) to set a SOAP 1.1/1.2 fault with Subcode at the server-side.Use soap_sender_fault_subcode(struct soap *soap, const char *subcode, const char *faultstring, const char *detail) to set a SOAP 1.1/1.2 unrecoverable Bad Request fault with Subcode at the server-side.gSOAP provides a function to duplicate a string into gSOAP's memory space:
| char *soap_strdup(struct soap *soap, const char *s) |
The function allocates space for s with soap_malloc, copies thestring, and returns a pointer to the duplicated string. When s is NULL,the function does not allocate and copy the string and returns NULL.
When a class declaration has a struct soap * field, this field will be set to point to the current gSOAP runtime context bygSOAP's deserializers and by the soap_new_Class functions.This simplifies memory management for class instances.The struct soap* pointer is implicitly set by the gSOAP deserializer forthe class or explicitly by calling the soap_new_X function for class X.For example:
| class Sample { public: struct soap *soap; // reference to gSOAP's run-time ... Sample(); ~Sample(); }; |
The constructor and destructor for class Sample are:
| Sample::Sample() { this->soap = NULL; } Sample::~Sample() { soap_unlink(this->soap, this); } |
The soap_unlink() call removes the object from gSOAP's deallocation chain.In that way, soap_destroy can be safely called to remove all class instances.The following code illustrates the explicit creation of a Sample object and cleanup:
| struct soap *soap = soap_new(); // new gSOAP runtime Sample *obj = soap_new_Sample(soap); // new Sample object with obj->soap set to runtime ... delete obj; // also calls soap_unlink to remove obj from the deallocation chain soap_destroy(soap); // deallocate all (other) class instances soap_end(soap); // clean up |
Here is another example:
| class ns__myClass { ... struct soap *soap; // set by soap_new_ns__myClass() char *name; void setName(const char *s); ... }; |
Calls to soap_new_ns__myClass(soap) will set the soap field in the class instance to the current gSOAPcontext. Because the deserializers invoke the soap_new functions, the soap field of the ns__myClassinstances are set as well.This mechanism is convenient when Web Service methods need to return objects that are instantiated in the methods.For example
| int ns__myMethod(struct soap *soap, ...) { ns__myClass *p = soap_new_ns__myClass(soap); p->setName("SOAP"); return SOAP_OK; } void ns__myClass::ns__setName(const char *s) { if (soap) name = (char*)soap_malloc(soap, strlen(s)+1); else name = (char*)malloc(strlen(s)+1); strcpy(name, s); } ns__myClass::ns__myClass() { soap = NULL; name = NULL; } ns__myClass::~ns__myClass() { if (!soap && name) free(name); soap_unlink(soap, this); } |
Calling soap_destroy right after soap_serve in the Web Service will destroy all dynamically allocatedclass instances.
To activate message logging for debugging, un-comment the #define DEBUG directive in stdsoap2.h. Compile the client and/orserver applications as described above (or simply use c++ -DDEBUG ... to compile with debugging activated). When the client and server applications run, they will log their activity in threeseparate files:
|
Caution: The client and server applications may run slow due to the logging activity.Caution: When installing a CGI application on the Web with debugging activated, the log files may sometimes not be created due to fileaccess permission restrictions imposed on CGI applications. To get around this, create empty log files with universal writepermissions. Be careful about the security implication of this.You can test a service CGI application without deploying it on the Web.To do this, create a client application for the service and activate message logging by this client.Remove any old SENT.log file and run the client (which connects to the Web service or to another dummy, but valid address)and copy the SENT.log file to another file, e.g. SENT.tst.Then redirect the SENT.tst file to the service CGI application. For example,
| > ./myservice.cgi < SENT.tst |
This should display the service response on the terminal.The file names of the log files and the logging activity can be controlled at the application level. This allows the creation ofseparate log files by separate services, clients, and threads.For example, the following service logs all SOAP messages (but no debug messages) in separate directories:
| struct soap soap; soap_init(&soap); ... soap_set_recv_logfile(&soap, "logs/recv/service12.log"); // append all messages received in /logs/recv/service12.log soap_set_sent_logfile(&soap, "logs/sent/service12.log"); // append all messages sent in /logs/sent/service12.log soap_set_test_logfile(&soap, NULL); // no file name: do not save debug messages ... soap_serve(&soap); ... |
Likewise, messages can be logged for individual client-side service operation calls.
The soapcpp2 -T option generates an auto-test server application in soapTester.cpp, which is to be compiled and linked with the code generated for a server implementation, i.e. soapServer.cpp (or with the generated server object class) and soapC.cpp. The feature also supports C, so use the soapcpp2 -c option to generate C.The auto-test server can be used to test a client application. Suppose thegenerated code is compiled into the executable named tester (compile soapServer.cpp, soapC.cpp, and stdsoap2.cpp or link libgsoap++). We can use the IOredirect to "send" it a message saved in a file, for example one of thesample request messages generated by soapcpp2:
| > ./tester < example.req.xml |
which then returns the response with default XML values displayed on the terminal.To run the auto test service on a port to test a client against, use two command-line arguments. The first argument is the OR-ed values of the gSOAP runtime context flags such as SOAP_IO_KEEPALIVE (0x10 = 16) and the second argument is the port number:
| > ./tester 16 8080 |
This starts an iterative stand-alone server on port 8080. This way, messagescan be sent to http://localhost:8080 to test the client. The data in theresponse messages are copied from the request messageswhen possible, or XML default values, or empty otherwise.
| > c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp -lsocket -lxnet -lnsl |
| > c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp -lsocket -lxnet -lnsl |
聯(lián)系客服
