gsoap中文文档（8.1.1）

8 快速指南
本指南旨在让你快速开始你的gSOAP开发之旅。阅读本节的内容，需要你对SOAP 1.1协议及C/C++语法有大体的了解。虽然使用gSOAP编译器可以直接用C/C++开始编写web服务及客户端程序而不需要了解SOAP协议的细节，但是由于我们在本节中使用了大量的实例来说明gSOAP与其他SOAP实现的连接及通讯，所以了解一些SOAP及WSDL协议也是必需的。

8.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 http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl
上面的命令根据制定URL提供的WSDL文档生成一个C++语法结构的头文件。
假如需要生成一个纯C的头文件，需要一下命令：
$ wsdl2h -c -o quote.h http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl
更多关于WSDL解析器及其选项的细节信息，请参见8.2.10节。
执行上述命令后，quote.h文件就生成了。其中包含开发客户端或服务端程序的存根例程定义。SOAP服务远程方法以函数声明的方式在这个头文件中被定义。C/C++源代码的存根例程将通过预编译器自动实现。同时，每个远程方法的程序框架也被自动生成了，它可以用来建立SOAP服务端程序应用。
SOAP服务的输入输出参数可以是简单的数据类型或复杂的数据结构，可以由WSDL解析器自动生成或手工定义。预编译器将自动生成序列化/反序列化这些数据的代码，以便存根例程可以将这些数据以XML的方式编码或解码。 8.1.1 例子
XMethods Delayed Stock Quote 服务提供一个getQuote方法（由'wsdl2h'WSDL解析器生成的quote.h定义）。这个方法根据提供的股票名称返回相应的股票价格。下面是这个方法的WSDL文档信息： Endpoint URL: http://services.xmethods.net:80/soap
SOAP action: "" (2 quotes)
Remote method namespace: urn:xmethods-delayed-quotes
Remote method name: getQuote
   Input parameter: symbol of type xsd:string
   Output parameter: Result of type xsd:float

下面是由WSDL解析器生成的getQuote.h头文件（实际的文件内容与'wsdl2h'版本及生成选项有关）：
//gsoap ns1 service name: net_DOTxmethods_DOTservices_DOTstockquote_DOTStockQuoteBinding
//gsoap ns1 service type: net_DOTxmethods_DOTservices_DOTstockquote_DOTStockQuotePortType
//gsoap ns1 service port: http://66.28.98.121:9090/soap
//gsoap ns1 service namespace: urn:xmethods-delayed-quotes
//gsoap ns1 service documentation: Definitions generated by the gSOAP WSDL parser 1.0
// Service net.xmethods.services.stockquote.StockQuoteService : net.xmethods.services.stockquote.StockQuote web service //gsoap ns1 service method-style: getQuote rpc
//gsoap ns1 service method-encoding: getQuote http://schemas.xmlsoap.org/soap/encoding/
//gsoap ns1 service method-action: getQuote urn:xmethods-delayed-quotes#getQuote
int ns1__getQuote(char *symbol, float &Result); 这个头文件用C/C++代码为gSOAP预编译器指定了web服务的细节。远程方法被定义为函数ns1__getQuote，同时指定了客户端调用web服务所需的所有细节信息。

getQuote远程方法需要一个名为symbol的字符串作为输入参数，同时需要一个名为Result的浮点数作为输出参数。预编译器生成的远程方法调用函数中，最后一个参数必须是输出参数，该参数以引用方式传递或定义为指针类型。除此之外的所有参数都是输入参数，这些参数必须以传值方式传递。函数返回一个整型值，其值说明web服务调用成功或出现的错误。具体的错误代码信息参见10.2节。
函数名中命名空间前缀ns1__的细节信息将在8.1.2节中讨论。简单的说，命名空间前缀与函数名之间用两个下划线分割。比如，ns1__getQuote中，ns1为命名空间前缀，getQuote是函数名称。（函数名中单个下划线将在XML中解释为破折号-，因为在XML中破折号比下划线更常用，细节请参见10.3节）
用下面命令执行预编译器：

soapcpp2 getQuote.h 预编译器根据getQuote.h中定义的信息来生成存根例程的代码框架。这个存根例程可以在客户端程序中随处调用。存根例程被声明为下面的样子： int soap_call_ns1__getQuote(strUCt soap *soap, char *URL, char *action, char *symbol, float &Result); 存根例程保存在soapClient.cpp文件中；soapC.cpp文件包含了序列化、反序列化数据的函数。你可以用 -c编译选项来生成纯C的代码。
注重，soap_call_ns1__getQuote在ns1__getQuote的参数基础上又增加了三个参数：soap必须是指向一个gSOAP运行环境的合法指针；URL是web服务的URL；action指明了web服务需要的SOAP action。XMethods Delayed Stock Quote服务的URL是http://66.28.98.121:9090/soap，action是"" (2 quotes)。你可以动态的改变URL及action。假如上述两个变量定义为NULL，则会使用头文件中定义的信息。
下面的例子调用远程方法获取IBM的股票信息： #include "soapH.h" // 包含生成的存根例程定义
#include "net_DOT_xmethods_DOT_services_DOT_stockquote_DOT_StockQuoteBinding.nsmap" // 包含命名空间表
int main()
{
   struct soap soap; // gSOAP运行环境
   float quote;
   soap_init(&soap); // 初始化运行环境（只执行一次）
   if (soap_call_ns1__getQuote(&soap, NULL, NULL, "IBM", &quote) == SOAP_OK)
      std::cout << "Current IBM Stock Quote = " << quote << std::endl;
   else // an error occurred
      soap_print_fault(&soap, stderr); // 在stderr中显示错误信息
   soap_destroy(&soap); // 删除类实例（仅用于C++中）
   soap_end(&soap); // 清楚运行环境变量
   soap_done(&soap); // 卸载运行环境变量
   return 0;
} 调用成功后，存根例程返回SOAP_OK同时quote变量保存着股票信息；假如调用失败则产生一个错误，同时通过soap_print_fault函数显示错误信息。
gSOAP编译器同时为C++客户端程序生成了一个代理类。 #include "soapnet_DOT_xmethods_DOT_services_DOT_stockquote_DOT_StockQuoteBindingProxy.h" // 获得代理
#include "net_DOT_xmethods_DOT_services_DOT_stockquote_DOT_StockQuoteBinding.nsmap" // 包含命名空间表
int main()
{
   net q; // "net" 是这个服务代理类的短名称
   float r;
   if (q.ns1__getQuote("IBM", r) == SOAP_OK)
      std::cout << r << std::endl;
   else
      soap_print_fault(q.soap, stderr);
   return 0;
} 代理类的构造函数定义并初始化了一个gSOAP环境变量实例。所有的HTTP及SOAP/XML处理被隐藏在后台处理。你可以改变WSDL解析器生成的头文件中web服务的名称。web服务的名字是由WSDL内容中萃取的，并不总是短名称格式的。你可以随意更改这个条目 //gsoap ns1 service name: net_DOT_xmethods_DOT_services_DOT_stockquote_DOT_StockQuoteBinding 来使用一个更合适的名字。这个名字将决定代理类文件及XML命名空间表文件的名字。

下面的函数可以用来建立一个gSOAP运行环境（struct soap）：
soap_init(struct soap *soap) 初始化运行环境变量（只需要执行一次）
soap_init1(struct soap *soap, soap_mode iomode) 初始化运行环境变量同时设置in/out模式
soap_init2(struct soap *soap, soap_mode imode, soap_mode omode) 初始化运行环境变量同时分别设置in/out模式
struct soap *soap_new() 定义、初始化运行环境并返回一个执行运行环境的指针
struct soap *soap_new1(soap_mode iomode) 定义、初始化运行环境并返回一个执行运行环境的指针并设置in/out模式
struct soap *soap_new2(soap_mode imode, soap_mode omode) 定义、初始化运行环境并返回一个执行运行环境的指针并分别设置in/out模式
struct soap *soap_copy(struct soap *soap) 定义一个新的环境变量并将现有环境信息赋值给新的变量
soap_done(struct soap *soap) 重置、关闭连接，清除环境变量

环境变量可以在程序中任意次数的使用。每个新的线程就需要一个新的环境变量实例。
当例子中的客户端程序执行时，SOAP请求通过soap_call_ns1__getQuote函数来调用，它生成下面的SOAP RPC请求信息：
POST /soap HTTP/1.1
Host: services.xmethods.net
Content-Type: text/xml
Content-Length: 529
SOAPAction: "" <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:ns1="urn:xmethods-delayed-quotes"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getQuote>
<symbol>IBM</symbol>
</ns1:getQuote>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope> XMethods Delayed Stock Quote 服务返回如下的信息：
HTTP/1.1 200 OK
Date: Sat, 25 Aug 2001 19:28:59 GMT
Content-Type: text/xml
Server: Electric/1.0
Connection: Keep-Alive
Content-Length: 491 <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
   soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/?
<soap:Body>
<n:getQuoteResponse xmlns:n="urn:xmethods-delayed-quotes?
<Result xsi:type="xsd:float?41.81</Result>
</n:getQuoteResponse>
</soap:Body>
</soap:Envelope> 服务返回的信息通过存根例程来解析，并保存在soap_call_ns1__getQuote函数的quote参数中。
客户端程序可以在任意时间多次调用远程方法。请看下面的例子： ...
struct soap soap;
float quotes[3]; char *myportfolio[] = {"IBM", "MSDN"};
soap_init(&soap); // need to initialize only once
for (int i = 0; i < 3; i++)
   if (soap_call_ns1__getQuote(&soap, "http://services.xmethods.net:80/soap", "", myportfolio[i], &quotes[i]) != SOAP_OK)
      break;
if (soap.error) // an error occurred
   soap_print_fault(&soap, stderr);

soap_end(&soap); // clean up all deserialized data
... 这个客户端程序通过调用ns1__getQuote存根例程来为数组中的每个股票代码获得信息。
上面的例子给我们示范了使用gSOAP创建一个SOAP客户端时多么轻易的事情啊。