gSOAP编译工具提供了一个SOAP/XML 关于C/C++ 语言的实现，从而让C/C++语言开发web服务或客户端程序的工作变得轻松了很多。绝大多数的C++web服务工具包提供一组API函数类库来处理特定的SOAP数据结构，这样就使得用户必须改变程序结构来适应相关的类库。与之相反，gSOAP利用编译器技术提供了一组透明化的SOAP API，并将与开发无关的SOAP实现细节相关的内容对用户隐藏起来。

gSOAP的编译器能够自动的将用户定义的本地化的C或C++数据类型转变为符合XML语法的数据结构，反之亦然。这样，只用一组简单的API就将用户从SOAP细节实现工作中解脱了出来，可以专注与应用程序逻辑的实现工作了。gSOAP编译器可以集成C/C++和Fortran代码（通过一个Fortran到C的接口），嵌入式系统，其他SOAP程序提供的实时软件的资源和信息；可以跨越多个操作系统，语言环境以及在防火墙后的不同组织。

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的方式编码或解码。