gsoap中文文檔（8.1.1）

2019-11-17 04:37:20

字體：大中小

來源：轉載

供稿：網友

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客戶端時多么輕易的事情啊。

上一篇：管理信息系統需求調研分析指南

下一篇：軟件項目質量管理經驗談