一、關于gsoap的預備知識
gsoap 2.x 新增函數
Function | Description |
soap_init(struct soap *soap) | Initializes a context (required only once) |
struct soap *soap_new() | Allocates, initializes, and returns a pointer to a runtime context |
struct soap *soap_copy(structsoap *soap) | Allocates a new runtime context and copies contents of the context such that the new environment does not share any data with the original context |
struct soap 是環境變量,可重複使用,動态申請的soap需要使用soap_free釋放。
如:
int main()
{
struct soap soap;
...
soap_init(&soap); // initialize runtime context
...
soap_call_ns__method1(&soap, ...); // make a remote call
...
soap_call_ns__method2(&soap, ...); // make another remote call
...
soap_destroy(&soap); // remove deserialized class instances (C++ only)
soap_end(&soap); // clean up and remove deserialized data
soap_done(&soap); // detach context (last use and no longer in scope)
...
}
也可以進行堆配置設定:
int main()
{
struct soap *soap;
...
soap = soap_new(); // allocate and initialize runtime context
if (!soap) // couldn't allocate: stop
...
soap_call_ns__method1(soap, ...); // make a remote call
...
soap_call_ns__method2(soap, ...); // make another remote call
...
soap_destroy(soap); // remove deserialized class instances (C++ only)
soap_end(soap); // clean up and remove deserialized data
soap_free(soap); // detach and free runtime context
}
服務端調用soap_server()前必須對環境進行初始化 soap_init()
int main() { struct soap soap; soap_init(&soap); soap_serve(&soap); } |
或
int main()
{
soap_serve(soap_new());
}
服務端可使用多線程來響應請求,當其他代碼在調用服務操作時。
int main()
{
struct soap soap1, soap2;
pthread_t tid;
...
soap_init(&soap1);
if (soap_bind(&soap1, host, port, backlog) < 0) exit(1);
if (soap_accept(&soap1) < 0) exit(1);
pthread_create(&tid, NULL, (void*(*)(void*))soap_serve, (void*)&soap1);
...
soap_init(&soap2);
soap_call_ns__method(&soap2, ...); // make a remote call
...
soap_end(&soap2);
...
pthread_join(tid, NULL); // wait for thread to terminate
soap_end(&soap1); // release its data
}
soap_print_fault() 列印錯誤資訊。
Function | Description |
soap_init(struct soap *soap) | Initializes a runtime context |
soap_init1(struct soap *soap, soap_mode iomode) | Initializes a runtime context and set in/out mode flags |
soap_init2(struct soap *soap, soap_mode imode, soap_mode omode) | Initializes a runtime context and set in/out mode flags |
struct soap *soap_new() | Allocates, initializes, and returns a pointer to a runtime context |
struct soap *soap_new1(soap_mode iomode) | Allocates, initializes, and returns a pointer to a runtime context and set in/out mode flags |
struct soap *soap_new2(soap_mode imode, soap_mode omode) | Allocates, initializes, and returns a pointer to a runtime context and set in/out mode flags |
struct soap *soap_copy(struct soap *soap) | Allocates a new runtime context and copies a context (deep copy, i.e. the new context does not share any data with the other context) |
soap_done(struct soap *soap) | Reset, close communications, and remove callbacks |
soap_free(struct soap *soap) | Reset and deallocate the context created with soap_new or soap_copy |
soap_bind(struct soap *soap, char *host, int port, int backlog) | Returns master socket (backlog = max. queue size for requests). When host==NULL: host is the machine on which the service runs |
soap_accept(struct soap *soap) | Returns slave socket |
soap_end(struct soap *soap) | Clean up deserialized data (except class instances) and temporary data |
soap_free_temp(struct soap *soap) | Clean up temporary data only |
Function | Description |
void soap_begin_send(struct soap*) | start a send/write phase |
int soap_end_send(struct soap*) | flush the buffer |
int soap_begin_recv(struct soap*) | start a rec/read phase (if an HTTP header is present, parse it first) |
int soap_end_recv(struct soap*) | perform a id/href consistency check on deserialized data |
二、wsdl2h 選項 wsdl2h是把wsdl或xml檔案生成.h檔案的工具
Option | Description |
-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 |
This option is for backward compatibility with gSOAP 2.4.1 and earlier. | |
The option does not produce code that conforms to WS-I Basic Profile 1.0a. | |
-f | generate flat C++ class hierarchy for schema extensions |
-g | generate global top-level element declarations |
-h | print help information |
-I path | use path to locate source files for #import |
-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 |
-N name | use name for service prefixes to produce a service for each binding |
-n name | use name as the base namespace prefix name instead of ns |
-o file | output to file |
-P | don't create polymorphic types inherited from xsd__anyType |
-p | create polymorphic types inherited from base xsd__anyType |
This is automatically performed when WSDL contains polymorphic definitions | |
-q name | use name for the C++ namespace of all declarations |
-r host[: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) |
-t file | 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 |
-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 |
-z5 | compatibility up to 2.8.17 |
-_ | don't generate _USCORE (replace with UNICODE _x005f) |
三、使用soapcpp2 工具生成c/c++架構代碼
選項
Option | Description |
-1 | Generate SOAP 1.1 bindings |
-2 | Generate SOAP 1.2 bindings |
-0 | No SOAP bindings, use REST |
-C | Generate client-side code only |
-S | Generate server-side code only |
-T | Generate server auto-test code |
-L | Do not generate soapClientLib/soapServerLib |
-a | Use SOAPAction with WS-Addressing to invoke server-side operations |
-A | Require SOAPAction to invoke server-side operations |
-b | serialize byte arrays char[N] as string |
-c | Generate pure C code |
-d < path > | Save sources in directory specified by < path > |
-e | Generate SOAP RPC encoding style bindings |
-f N | File split of N XML serializer implementations per file |
-h | Print a brief usage message |
-i | Generate service proxies and objects inherited from soap struct |
-j | Generate C++ service proxies and objects that can share a soap struct |
-I < path > | Use < path > for #import (paths separated with ':' or ';' for windows) |
-k | generate data structure walkers (experimental) |
-l | Generate linkable modules (experimental) |
-m | Generate Matlabtm code for MEX compiler |
-n | When used with -p, enables multi-client and multi-server builds: |
Sets compiler option WITH_NONAMESPACES, see Section 9.11 | |
Saves the namespace mapping table with name < name > _namespaces instead of namespaces | |
Renames soap_serve() into < name > _serve() and soap_destroy() into < name > _destroy() | |
-p < name > | Save sources with file name prefix < name > instead of "soap" |
-q < name > | Use name for the C++ namespace of all declarations |
-s | Generates deserialization code with strict XML validation checks |
-t | Generates code to send typed messages (with the attribute) |
-u | uncomment comments in WSDL/schema output by suppressing XML comments |
-v | Display version info |
-w | Do not generate WSDL and schema files |
-x | Do not generate sample XML message files |
-y | include C/C++ type access information in sample XML messages |
-z1 | compatibility: generate old-style C++ service proxies and objects |
-z2 | compatibility with 2.7.x: omit XML output for NULL pointers |
生成的代碼:
File Name ------------------------------ | Description |
soapStub.h | A modified and annotated header file produced from the input header file |
soapH.h | Main header file to be included by all client and service sources |
soapC.cpp | Serializers and deserializers for the specified data structures |
soapClient.cpp | Client stub routines for remote operations |
soapServer.cpp | Service skeleton routines |
soapClientLib.cpp | Client stubs combined with local static (de)serializers |
soapServerLib.cpp | Service skeletons combined with local static (de)serializers |
soapXYZProxy.h | A C++ proxy object (link with soapC.cpp soapClient.cpp) |
soapXYZProxy.h | With option -i: proxy object (link with soapC.cpp and soapXYZProxy.cpp) |
soapXYZProxy.cpp | With option -i: proxy code |
soapXYZObject.h | A C++ server object (link with soapC.cpp and soapServer.cpp) |
soapXYZService.h | With option -i: server object (link with soapC.cpp and soapXYZService.cpp) |
soapXYZService.cpp | With option -i: server code |
.xsd | An ns.xsd file is generated with an XML Schema for each namespace prefix ns used by a data structure in the header file input to the compiler, |
.wsdl | A ns.wsdl file is generated with an WSDL description for each namespace prefix ns used by a service operation in the header file input to the compiler |
.xml | Several SOAP/XML request and response files are generated. These are example message files are valid provided that sufficient schema namespace directives are added to the header file or the generated .nsmap namespace table for the client/service is not modified by hand |
.nsmap | A ns.nsmap file is generated for each namespace prefix ns used by a service operation in the header file input to the compiler, see Section 7.2.9. The file contains a namespace mapping table that can be used in the client/service sources |
會使用到的gsoap包
File Name | Description |
stdsoap2.h | Header file of stdsoap2.cpp runtime library |
stdsoap2.c | Runtime C library with XML parser and run-time support routines |
stdsoap2.cpp | Runtime C++ library identical to stdsoap2.c |
四、記憶體管理
Function Call | Description |
soap_destroy(struct soap *soap) | Remove all dynamically allocated C++ objects. |
must be called before soap_end() | |
soap_end(struct soap *soap) | Remove temporary data and deserialized data except |
class instances | |
soap_free_temp(struct soap *soap) | Instead of soap_destroy and soap_end: |
remove temporary data only | |
soap_dealloc(struct soap *soap, void *p) | Remove malloced data at p. When p==NULL: remove all |
dynamically allocated (deserialized) data except class instances | |
soap_delete(struct soap *soap, void *p) | Remove class instance at p. When p==NULL: remove all |
dynamically allocated (deserialized) class instances | |
(this is identical to calling soap_destroy(struct soap *soap)) | |
soap_unlink(struct soap *soap, void *p) | Unlink data/object at p from gSOAP's deallocation chain |
so gSOAP won't deallocate it | |
soap_done(struct soap *soap) | Detach context (reset runtime context) |
soap_free(struct soap *soap) | Detach and free context (allocated with soap_new) |
使用以下函數來配置設定臨時資料,可以自動回收
Function Call | Description |
void *soap_malloc(struct soap *soap, size_t n) | return pointer to n bytes |
Class *soap_new_Class(struct soap *soap) | instantiate Class |
Class *soap_new_Class(struct soap *soap, int n) | instantiate array of n objects |
Class *soap_new_set_Class(struct soap *soap, m1, ..., mn) | instantiate and set members mi |
Class *soap_new_req_Class(struct soap *soap, m1, ..., mn) | instantiate and set required-only mi |