|
Soap是一個在信息交換中使用得非常廣泛的協議，使用方便，并直接可與HTTP, SMTP等其它協議一起工作。本文討論如何使用Microsoft SOAP Tookit的C++來建立一個簡單的SOAP客戶端應用。
=========================================================
一、先決條件：
必須熟悉使用COM，特別要熟悉COM中的Smart Pointers。我通過導入方法將COM接口轉換成Smart Pointers。系統必須安裝了Microsoft SOAP Toolkit和Microsoft XML Parser。文末參考一節介紹如何下載工具箱。文末附件可下載本文源程序。
二、SOAP編程基礎：
下面開始介紹一個簡單SOAP應用中所包含的類。在此之前，必需先導入所需的類型庫，然后程序才能夠使用SOAP的類。
導入類型庫：
SOAP中使用的對象和接口都在mssoap1.dll文件中。這個文件在安裝Microsoft SOAP Toolkit 2.0時生成，存在路徑："C:\Program Files\Common Files\MSSoap\Binaries\MSSOAP1.dll"。用#import將該文件導入到程序中。類型庫的內容在導入時被轉換成COM smart pointers來描述COM接口。因為SOAP完全依賴于XML，因此必需用Microsoft XML Parser來處理XML。Microsoft XML parser在msxml3.dll文件里。這個文件要在導入mssoap1.dll之前導入。
#import "msxml3.dll"
using namespace MSXML2;
#import "C:\Program Files\Common Files\MSSoap\Binaries\MSSOAP1.dll" \
exclude("IStream", "ISequentialStream", "_LARGE_INTEGER", \
"_ULARGE_INTEGER", "tagSTATSTG", "_FILETIME")
using namespace MSSOAPLib;
上面這些代碼是編寫SOAP程序必需包含的。
建立SOAP客戶端應用有以下三步驟：
1- 指定和連接Web服務器。
2- 準備和發送消息。
3- 讀取服務端返回的信息。
下面是在基本SOAP客戶端要使用到的類：
1- SoapConnector:
在客戶/服務模式下，首先要做的事就是連接服務器。SoapConnector類執行客戶端與服務端之間的消息傳送協議。 SoapConnector是一個抽象類，定義了協議執行的接口。事實上， SoapConnector類不定義執行某種特定的傳送協議，例如：MSMQ, MQ Series, SMTP 和 TCP/IP等。 為簡便起見，本文只說明使用HTTP傳送協議，它是由Microsoft SOAP Toolkit 2.0中的HttpConnector 類來執行的。
SoapConnector類使用步驟如下：
a) 創建SoapConnector類對象：
ISoapConnectorPtr connector;
Connector.CreateInstance(__uuidof(HttpConnector));
b) 指定Web服務器地址：
指定服務器，要做二件事：選擇HttpConnector的屬性和相應的屬性值。本文示例選用EndPointURL屬性：
Connector->Property ["EndPointURL"] = "some url pointing to web service";
以下是屬性選項說明(屬性名是大小寫敏感的)：
AuthPassword：客戶口令
AuthUser：客戶名
EndPointURL ：客戶URL
ProxyPassword： 代理(proxy)口令
ProxyPort ：代理斷口
ProxyServer ：代理服務器的IP地址或主機名
ProxyUser ：代理用戶名
SoapAction：HTTP的抬頭值。這個屬性只使用于低級API。它將忽略SoapClient接口(高級API)中的ConnectorProperty屬性 。
SSLClientCertificateName：指定使用Secure Sockets Layer (SSL)加密協議。語法如下：
[CURRENT_USER | LOCAL_MACHINE\[store-name\]]cert-name with the defaults being CURRENT_USER\MY (與Microsoft Internet Explorer用法相同)。
Timeout：HttpConnector的超時限制，以毫秒為單位。
UseProxy：定義是否使用代理(proxy)。缺省值為False。如果將這個屬性為真(True)，又沒有設置上面的ProxyServer值，代理服務器將使用IE里的代理服務器。此時HttpConnector將不理會IE的"Bypass Proxy"(繞道)設置。
UseSSL：定義是否使用SSL(True 或 False)。此值設置為真時，HttpConnector對象不管WSDL設置是HTTP或HTTPS都用SSL連接方式。若此值設置為非真，HttpConnector對象只在WSDL設置為HTTPS時才用SSL方式連接。
c) 與Web服務器連接：
Connector->Connect();
d) 指定動作：
Connector->Property ["SoapAction"] = "some uri";
e) 啟動消息句柄：
必需在SoapSerializer(消息準備函數)之前先啟動消息處理機制
Connector->BeginMessage();
在消息處理完畢之后，用EndMessage()函數將消息送往服務器。
.
.
[ 消息準備代碼 ]
.
.
Connector->EndMessage();
以上就是與服務器連接的過程。下面介紹如何創建和準備消息。
SoapSerializer:
用于建立送往服務器的SOAP消息。在與服務器通訊之前，SoapSerializer對象必需先與SoapConnector對象連接。SoapSerializer的初始化函數將建立這個內部連接。初始化代入的參數是InputStream (數據流)：
// 創建SoapSerializer對象，并用InputSTream進行初始化。
ISoapSerializerPtr Serializer;
Serializer.CreateInstance(_uuidof(SoapSerializer));
Serializer->Init(_variant_t((IUnknown*)Connector->InputStream));
下面是SOAP請求代碼：
<SOAP: Envelope xmlns:SOAP="soap namespace">
<SOAP:Body>
<m:someMethodName xmlns:m="some namespace">
<someParameter> someParameterValue </someParameter>
<m:someMethodName>
</SOAP:Body>
</SOAP: Envelope>
SOAP請求被安放在標記之中。<Envelope>是SOAP文件的主標記。SOAP信息通常都安放在”信封“(Envelope)里。信封里的<Body>標記中安放信息體，其中包含具體請求。在C++里，用相應的方法來解釋這些標記并定義有關的值。
下面的代碼說明如何使用這些方法：
Serializer->startEnvelope("SOAP","","");
// 開始處理SOAP消息。第一個參數是命名空間，缺省為SOAP-ENV。
// 第二個參數定義URI。第三個參數定義Serialzier->startBody("")函數的編碼方式。
// 開始處理<Body>元素，第一個參數是URI的編碼類型，缺省為NONE。
Serializer->startElement("someMethodName","","","m");
// 開始處理Body里的子元素。
// 第一個參數是元素名。第二個參數是URI。
// 第三個參數編碼類型。第四個參數是元素的命名空間。
Serializer->WriteString("someParameterValue")
// 寫入元素值
在上面的每個startXXX函數后都要又相應的endXXX函數來結尾。消息做完之后，連接器就調用endMessage()方法將消息發送到服務器。
至此，我們已經連接了服務器，制作了相應的消息。最后一個步驟就是接收服務器回應。
SoapReader:
讀取服務器返回的信息，將信息解析之后裝入DOM，為進一步處理所用。下面是服務器返回的SOAP回應信息：
<SOAP: Envelope xmlns:SOAP="soap namespace">
<SOAP:Body>
<m:someMethodNameResponse xmlns:m="some namespace">
<return> someResult </return>
<m:someMethodNameResponse>
</SOAP:Body>
</SOAP: Envelope>
使用OutputStream來讀取SoapReader對象中的信息。(OutputStream接收服務器返回的信息)。
// 創建SOAPReader對象，并連接到outputstream
ISoapReaderPtr Reader;
Reader.CreateInstance(_uuidof(SoapReader));
Reader->Load(_variant_t((IUnknown*)Connector->OutputStream));
// load方法還可以用于加載XML文件或字符串
將回應信息加載到SoapReader對象之后，就可以用它的RPCResult屬性來獲取結果。不過，But RPCResult并不直接返回結果，它返回<Body>的第一個實體元素，然后用text屬性讀取該元素屬性值：
Reader->RPCResult->text
三、舉例說明一個簡單的SOAP客戶端應用：
本文示例用www.xmethods.net做服務器。這個服務器指向Yahoo在線信息。
可以在http://www.xmethods.net/ve2/ViewListing.po?serviceid=156找到有關細節。
下面的代碼中要輸入一個參數，即Yahoo的用戶ID。返回結果為0表示離線，1表示在線。
其他細節可參閱：http://www.allesta.net:51110/webservices/wsdl/YahooUserPingService.xml
四、參考：
The SOAP specification Simple Object Access Protocol (SOAP) 1.1 - W3C Note ：
http://www.w3.org/TR/SOAP
Microsoft SOAP Toolkit Download ：
http://download.microsoft.com/download/xml/soap/2.0/w98nt42kme/EN-US/SoapToolkit20.exe
五：本文示例的SOAP代碼：
#include <stdio.h>
#import "msxml3.dll"
using namespace MSXML2;
#import "C:\Program Files\Common Files\MSSoap\Binaries\MSSOAP1.dll" \
exclude("IStream", "ISequentialStream", "_LARGE_INTEGER", \
"_ULARGE_INTEGER", "tagSTATSTG", "_FILETIME")
using namespace MSSOAPLib;
void main()
{
CoInitialize(NULL);
ISoapSerializerPtr Serializer;
ISoapReaderPtr Reader;
ISoapConnectorPtr Connector;
// 連接服務器
Connector.CreateInstance(__uuidof(HttpConnector));
Connector->Property["EndPointURL"] = "http://www.allesta.net:51110/webservices/soapx4/isuseronline.php";
Connector->Connect();
// 啟動消息機制
Connector->Property["SoapAction"] = "uri:allesta-YahooUserPing";
Connector->BeginMessage();
// 創建SoapSerializer對象
Serializer.CreateInstance(__uuidof(SoapSerializer));
// 與輸入流連接
Serializer->Init(_variant_t((IUnknown*)Connector->InputStream));
// 制作SOAP信息
Serializer->startEnvelope("","","");
Serializer->startBody("");
Serializer->startElement("isuseronline","uri:allesta-YahooUserPing","","m");
Serializer->startElement("username","","","");
Serializer->writeString("laghari78");
Serializer->endElement();
Serializer->endElement();
Serializer->endBody();
Serializer->endEnvelope();
// 向服務器發送信息
Connector->EndMessage();
// 讀取回應
Reader.CreateInstance(__uuidof(SoapReader));
// 連接輸出流
Reader->Load(_variant_t((IUnknown*)Connector->OutputStream), "");
// 顯示結果
printf("Answer: %s\n", (const char *)Reader->RPCResult->text);
CoUninitialize();
}
本文附件
http://www.topxml.com/snippetcentral/snippetfiles/v20020425121357.zip
|
