标题：gSoap
简介
gSOAP的编译器能够自动的将用户定义的本地化的C或C++数据类型转变为符合XML语法的数据结构，反之亦然。这样，只用一组简单的API就将用户从SOAP细节实现工作中解脱了出来，可以专注与应用程序逻辑的实现工作了。gSOAP编译器可以集成C/C++和Fortran代码（通过一个Fortran到C的接口），嵌入式系统，其他SOAP程序提供的实时软件的资源和信息；可以跨越多个操作系统，语言环境以及在防火墙后的不同组织。
gSOAP一种跨平台的C和 C++软件开发工具包。生成C/C++的RPC代码，XML数据绑定，对SOAP Web服务和其他应用形成高效的具体架构解析器，它们都受益于一个XML接口。 这个工具包提供了一个全面和透明的XML数据绑定解决方案，Autocoding节省大量开发时间来执行SOAP/XML Web服务中的C/C++。此外，使用XML数据绑定大大简化了XML自动映射。应用开发人员不再需要调整应用程序逻辑的具体库和XML为中心的数据，如 交涉DOM。[1]
特点
可移植性：gSOAP支持大多 数平台，包括嵌入式系统和小系统（例如嵌入式Symbian，Palm）。可移植性测试Windows（98，XP，Vista），Linux，Unix 系统，Mac OS X，Solaris，HP-UX，AIX，FreeBSD，TRU64，Irix，QNX，VxWorks。
稳定性：该软件已经成熟。自2001年以来经过几年的发展和试验。许多工业项目和产品都在使用该软件。
广泛的用户群：自2003年以来超过150000次下载，成千上万许可证/支持协议的公司，其中包括一些财富100强企业。
所有功能于一身的软件包：独立第三方工具和库确保可靠的运行执行。
开源：可选择自由和商业许可。
C和C++的支持：支持纯粹的ANSI C和混合的C/C++应用开发。
综合XML数据绑定： gSOAP是唯一的SOAP/XML工具包，支持一个纯粹的本地的C/C++数据绑定到XML。该工具包是以自动序列指针为基础的数据结构。
行业标准协议： SOAP 1.1/1.2 WSDL 1.1，v2和UDDI 。支持XML架构原始XSD结构类型等等。
传 输：HTTP/S, TCP, UDP, MIME (SwA), DIME (streaming), MTOM (streaming), HTTP1.0/1.1, IPv4, IPv6, RSS, XML-RPC, WS-Addressing, WS-Enumeration等
安全：HTTPS和WS安全性：认证令牌，数字签名。
速度：架构特定的编译器生成的代码速度快。基准测试表明速度优于最快的XML解析器。
占用内存小：客户端应用程序总运行内存占用很小。内存管理使用垃圾收集，可以自动清理。 
许多例子：软件包，包括许多代码范例，其中包括独立的HTTP/1.1和HTTPS安全的Web服务器。
Web服务器整合：包括Apache_mod, IIS, WinInet, CGI, FastCGI。[1]
gSOAP使编写web服务的工作最小化了。gSOAP编译器生成SOAP的代码来序列化或反序列化C/C++的数据结构。gSOAP包含一个WSDL生成器，用它来为你的web服务生成web服务的解释。gSOAP的解释器及导入器可以使用户不需要分析web服务的细节就可以实现一个客户端或服务端程序。
下面是gSOAP的一些特点：
×gSOAP编译器可以根据用户定义的C和C++数据结构自动生成符合SOAP的实例化代码。
×gSOAP支持WSDL 1.1, SOAP 1.1, SOAP 1.2, SOAP RPC 编码方式以及 literal/document 方式.
×gSOAP是少数完全支持SOAP1.1 RPC编码功能的工具包，包括多维数组及动态类型。比如，一个包含一个基类参数的远程方法可以接收客户端传来的子类实例。子类实例通过动态绑定技术来保持一致性。
×gSOAP 支持 MIME (SwA) 和 DIME 附件包。
×gSOAP是唯一支持DIME附件传输的工具包。它允许你在保证XML可用性的同时能够以最快的方式（流方式）传递近乎无大小限制的二进制数据。
×gSOAP 支持 SOAP-over-UDP。
×gSOAP 支持 IPv4 and IPv6. 
×gSOAP 支持 Zlib deflate and gzip compression（for HTTP, TCP/IP, and XML file storage）。
×gSOAP 支持 SSL (HTTPS)。
×gSOAP 支持 HTTP/1.0, HTTP/1.1 保持连接, 分块传输及基本验证。 
×gSOAP 支持 SOAP 单向消息。
×gSOAP 包含一个 WSDL 生成器，便于web服务的发布。
×gSOAP 包含一个WSDL解析器（将WSDL转换为gSOAP头文件），可以自动化用户客户端及服务端的开发。
×生成可以单独运行的web服务及客户端程序。
×因为只需要很少内存空间，所以可以运行在类似Palm OS, Symbian, Pocket PC的小型设备中。
×适用于以C或C++开发的web服务中。
×跨平台：Windows, Unix, Linux, Mac OS X, Pocket PC, Palm OS, Symbian等。
×支持序列化程序中的本地化C/C++数据结构。
×可以使用输入和输出缓冲区来提高效率，但是不用完全消息缓冲来确定HTTP消息的长度。取而代之的是一个三相序列化方法。这样，像64位编码的图像就可以在小内存设备（如PDA）中以DIME附件或其他方式传输。
×支持C++单继承，动态绑定，重载，指针结构（列表、树、图、循环图，定长数组，动态数组，枚举，64位2进制编码及16进制编码）。
×不需要重写现有的C/C++应用。但是，不能用unions，指针和空指针来作为远程方法调用参数的数据结构中元素。
×三相编组：1）分析指针，引用，循环数据结构；2）确定HTTP消息长度；3）将数据序列化位SOAP1.1编码方式或用户定义的数据编码方式。
×双相编组：1）SOAP解释及编码；2）分解“forward”指针（例如：分解SOAP中的href属性）。
×完整可定制的SOAP错误处理机制。
×可定制的SOAP消息头处理机制，可以用来保持状态信息
2 gSoap2.2版与gSOAP 2.1版（或以前版本）的不同
如果你是从2.1版升级到2.2或以后版本，请注意这些变化。
为了能够分离传输、内容编码、映射中的接收/发送设置，改变了运行时选项及标志。这些标志分布再四个类中：传输（IO），内容编码（ENC），XML编组（XML）及C/C++数据映射。不再提倡使用旧标志soap_disable_X及soap_enable_X（其中，X表示选项名）。具体内容请参见9.12节。
3. gSoap2.x版与gSOAP 1.x版的不同
如果你是从1.x版升级到2.x版，请注意下面的内容。
gSOAP2.0及之后的版本是在1.x版基础上重写的。gSOAP2.0之后的版本是线程安全的，但之前版本不是。gSOAP2.x版本中的主要文件已经重新命名，以便与1.x版区分。
gSOAP 1.X gSOAP 2.X 
soapcpp soapcpp2 
soapcpp.exe soapcpp2.exe 
stdsoap.h stdsoap2.h 
stdsoap.c stdsoap2.c 
stdsoap.cpp stdsoap2.cpp 
从1.x版升级到2.x版并不需要进行大量的代码重写工作。所有2.x版相关的函数都定义在stdsoap2.c[pp]文件中，这个文件是由gSOAP编译器自动生成的。所以，用1.x版开发的服务端或客户端代码需要进行修改以适应2.x版中函数的变化：在2.x版中，所有的gSOAP函数都增加了一个参数用来保存一个gSOAP运行环境实例。这个参数包括了文件描述，表，缓冲，标志位等，它在所有gSOAP函数中都是第一个参数。
gSOAP运行环境实例是一个struct soap类型的变量。当客户端程序访问远程方法前或当服务端程序能够接收一个请求前，必须先将这个运行环
境变量初始化。在2.x版中新增了3个函数来负责这些事情：
函数 解释
soap_init(struct soap *soap) 初始化环境变量（只需执行一次）
struct soap *soap_new() 定义并初始化环境变量并返回一个该变量的指针
struct soap *soap_copy(struct soap *soap) 定义一个环境变量并从已有的环境变量中拷贝环境信息
环境变量定义好后就可以重复使用而不必再次初始化了。只有当线程独占访问时，我们才需要一个新的环境变量。例如，下面的代码分配了
一个用于多个远程方法的环境变量：
int main() 
{ 
struct soap soap; 
... 
soap_init(&soap); // 初始化环境变量
... 
soap_call_ns__method1(&soap, ...); // 调用一个远程方法
... 
soap_call_ns__method2(&soap, ...); // 调用另一个远程方法
... 
soap_end(&soap); // 清除环境变量
... 
} 
我们也可以像下面这样定义环境变量：
int main() 
{ 
struct soap *soap; 
... 
soap = soap_new(); // 定义并初始化环境变量
if (!soap) // 如果不能定义，退出
... 
soap_call_ns__method1(soap, ...); // 调用远程函数
... 
soap_call_ns__method2(soap, ...); // 调用另一个远程函数
... 
soap_end(soap); // 清除环境变量
... 
free(soap); // 释放环境变量空间
} 
服务端代码在调用soap_serve函数前，需要定义相关环境变量:
int main() 
{ 
struct soap soap; 
soap_init(&soap); 
soap_serve(&soap); 
}
或者像下面这样:
int main() 
{ 
soap_serve(soap_new()); 
}
soap_serve函数用来处理一个或多个（当允许HTTP keep-alive时，参见18.11节中的SOAP_IO_KEEPALIVE标志）请求。
一个web服务可以用多线程技术来处理请求：
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, ...); // 调用远程方法
... 
soap_end(&soap2); 
... 
pthread_join(tid, NULL); // 等待线程结束
soap_end(&soap1); // 释放环境变量
}
在上面的例子中，需要两个环境变量信息。而在1.x版本中，由于静态分配环境变量，多线程技术是不被允许的（只有一个线程可以用这个环
境变量调用远程方法或处理请求信息）。
4 准备工作
要开始用gSOAP创建一个web服务应用, 你需要:
一个C/C++编译器. 
拥有根据操作系统平台创建的可执行的gSOAP的stdsoap2（windows下为stdsoap2.exe）编译器。
拥有根据操作系统平台创建的可执行的gSOAP的wsdl2h（windows下为wsdl2h.exe）WSDL解析器。
需要'stdsoap2.c'或'stdsoap2.cpp'及'stdsoap2.h'文件来实现你的SOAP功能。你可以创建一个dll或动态库以便简化连接。
如果你要支持SSL（HTTPS）及压缩的话，可以安装OpenSSL及Zlib库。
gSOAP是独立开发包，不需要任何第三方的软件支持（除非你要用到OpenSSL及Zlib）。
与平台无关的gSOAP版本需要你下面的工具编译'soapcpp2'及'wsdl2h'文件：
一个C++编译器（用来编译'wsdl2h'WSDL解析器）。
Bison 或 Yacc
Flex 或 Lex
推荐使用Bison及Flex。
在软件包samples目录下有大量的开发实例。可以用'make'来编译这些例子。这些例子包含了gSOAP中的各个方面。其中，最简单的例子是
one-liners（samples/oneliners）。
5 快速指南
本指南旨在让你快速开始你的gSOAP开发之旅。阅读本节的内容，需要你对SOAP 1.1协议及C/C++语法有大体的了解。虽然使用gSOAP编译器可
以直接用C/C++开始编写web服务及客户端程序而不需要了解SOAP协议的细节，但是由于我们在本节中使用了大量的实例来说明gSOAP与其他SOAP
实现的连接及通讯，所以了解一些SOAP及WSDL协议也是必需的。
5.1 如何使用gSOAP编译环境来编译SOAP客户端程序
通常，一个SOAP客户端应用的实现需要为每个客户端需要调用的远程方法提供一个存根例程（stub routine）。存根例程主要负责编码参数信息；将包含参数信息的调用请求发送给制定的SOAP服务；等待返回结果；将结果中的参数信息编码。客户端程序调用访问远程方法的存根例程
就像调用本地方法一样。用C/C++手工别写一个存根例程是个十分痛苦的差使，尤其当远程方法的参数中包含特定的数据结构（如：记录、数组、图等）时。幸运的是，gSOAP包中的'wsdl2h'WSDL解析器和'soapcpp2’存根及架构编译器能够将web服务客户端及服务端的开发工作自动化。
'soapcpp2’存根及架构编译器是可以生成构建C++ SOAP客户端所需的C++源码的预编译器。该预编译器的输入参数是一个标准的C/C++头文件。这个头文件可以由WSDL解析器根据相关的WSDL文档自动生成。
参见下面的命令：
$ wsdl2h -o quote.h
上面的命令根据制定URL提供的WSDL文档生成一个C++语法结构的头文件。
如果需要生成一个纯C的头文件，需要一下命令：
$ wsdl2h -c -o quote.h
更多关于WSDL解析器及其选项的细节信息，请参见8.2.10节。
执行上述命令后，quote.h文件就生成了。其中包含开发客户端或服务端程序的存根例程定义。SOAP服务远程方法以函数声明的方式在这个头文件中被定义。C/C++源代码的存根例程将通过预编译器自动实现。同时，每个远程方法的程序框架也被自动生成了，它可以用来建立SOAP服务端程序应用。
SOAP服务的输入输出参数可以是简单的数据类型或复杂的数据结构，可以由WSDL解析器自动生成或手工定义。预编译器将自动生成序列化/反序列化这些数据的代码，以便存根例程可以将这些数据以XML的方式编码或解码。
6 如何建立客户端程序代理类
用于C++客户端程序的代理类信息是由gSOAP 预编译器自动创建的。为了说明代理类的
生成过程，我们在getQuote.h 头文件中加入一些信息，以便gSOAP 预编译器可以生成代
理类。这些信息就类似于WSDL 解析器自动生成的头文件中就已经包含的信息。
//"getQuote.h"的内容:
//gsoap ns1 service name: Quote
//gsoap ns1 service location:XXX
//gsoap ns1 service namespace: urn:xmethods-delayed-quotes
//gsoap ns1 service style: rpc
//gsoap ns1 service encoding: encoded
//gsoap ns1 service method-action: getQuote ""
int ns1__getQuote(char *symbol, float &Result);
前三行指令用于定义代理类的名称，服务地址，命名空间。第四行、第五行指令定义
了使用SOAP RPC 编码方式。最后一行定义了可选的SOAPAction。当需要SOAPActio
n 时，这行信息将提供给每个远程方法。使用soapcpp2 对该头文件进行编译后，将会产
生soapQuoteProxy.h 文件。它包含下面的内容：
#include "soapH.h"
class Quote
{ public:
struct soap *soap;
const char *endpoint;
Quote() { soap = soap_new(); endpoint = "XXX"; };
~Quote() { if (soap) { soap_destroy(soap); soap_end(soap); soap_done
(soap); free((void*)soap); }};
int getQuote(char *symbol, float &Result) { return soap ? soap_call_ns1__getQuote(soap, endpoint, "", symbol, Result) : SOAP_EOM; };
};
为了能够在运行时刻对gSOAP 环境变量及命名空间进行定制，上述两个变量被定义
程全局变量。
生成的代理类可以同命名空间表一起包含在客户端程序中，请看下面的例子：
#include "soapQuoteProxy.h" // 获得代理类
#include "Quote.nsmap" // 获得命名空间绑定
int main()
{
Quote q;
float r;
if (q.ns1__getQuote("IBM", r) == SOAP_OK)
std::cout << r << std::endl;
else
soap_print_fault(q.soap, stderr);
return 0;
}
Quote 构造函数定义并初始化了一个gSOAP 运行环境实例。所有的HTTP 及SOAP
/XML 进程都被隐藏在后台自动执行。
如果你需要多个命名空间表或要联合多个客户端，你可以在执行soapcpp2 时添加参数-n
及-p 来生成命名空间表以防止冲突。