Web Services--gSOAP 2.7.6 第七章(7.1.1)

下载地址：http://sourceforge.net/projects/gsoap2

官方网站：http://genivia.com/Products/gsoap/index.html

本文翻译只是出于学习的目的，中文部分仅代表个人观点，有错误还望指正，英文部分来自gsoap-win32-2.7\doc\soapdoc2.pdf。其中复制可能有误，可以看懂英文的还请到官网下载。如有版权争议，请联系QQ：643166601，本人会及处理。翻译新手，有错是必然的，求高人指点。欢迎同为新手的你共同学习。

 

7.1.1 Example

7.1.1 列子

The getQuote remote method of XMethods Delayed Stock Quote service (defined in the quote.h file obtained with the ’wsdl2h’ WSDL parser) provides a delayed stock quote for a given ticker name.

XMethods的getQuote远程方法延迟的股票报价服务 (在quote.h文件中定义用‘wsdl2h’WSDL解析器获得)提供一个延时存储引用对于给定的票名称。

The WSDL description of the XMethods Delayed Stock Quote service provides the following details:

这个XMethods的延迟的股票报价服务的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

 

The following getQuote.h header file for C is created from the WSDL description with the WSDL parser (the actual contents may vary depending on the ’wsdl2h’ release version and the options used to determine the output):

以下的C头文件getQuote.h来自WSDL描述的WSDL解析器(这是实际的内容可能在‘wsdl2’发行版本中变化和使用的选项决定输出有关)：

 

//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);

 

The header file essentially specifies the service details in C/C++ with directives for the gSOAP compiler. 

这个头文件本质上指定了在用C/C++时用正式的指示给gSOAP编译器。

The remote method is declared as a ns1__getQuote function prototype which specifies all of the necessary details for the gSOAP compiler to generate the stub routine for a client application to interact with the Delayed Stock Quote service. 

这个远程方法声明ns1__getQuote函数属性指定gSOAP编译器生成stub程序客户端相互作用的Delayed Stock Quote服务应用的所有必要的细节。

The Delayed Stock Quote service description requires that the input parameter of the getQuote remote method is a symbol parameter of type string. 

这延迟的股票报价服务描述请求，输入一个远程getQuote的参数是一个符号，参数类型是字符串。

The description also indicates that the Result output parameter is a floating point number that represents the current unit price of the stock in dollars. 

这个描述也表明，结果输出参数是一个浮点数，代表当前用美元的股票价格。

The gSOAP compiler uses the convention the last parameter of the function prototype must be the output parameter of the remote method, which is required to be passed by reference using the reference operator (&) or by using a pointer type. 

这个gSOAP编译器使用这个约定，这个函数原型的最后一个参数必须是远程方法的输出参数，被请求通过引用使用引用操作符(&)或者使用指针类型。

All other parameters except the last are input parameters of the remote method, which are required to be passed by value or passed using a pointer to a value (by reference is not allowed). 

在所有的参数中除了最后远程方法的输入参数，被请求的通过值或通过指针传入值(不允许通过引用)。

The function prototype associated with a remote method is required to return an int, whose value indicates to the caller whether the connection to a SOAP Web service was successful or resulted in an exception, see Section 9.2 for the error codes.

这个函数原型结合请求远程方法返回值是int，这个返回值指示给调用者，其中的哪一个，连接到SOAP Web service是成功的或异常结果，看错误代码在9.2部分。

 

The use of the namespace prefix ns1__ in the remote method name in the function prototype declaration is discussed in detail in 7.1.2. 

在函数原型声明的远程方法名字中使用命名空间前缀ns1__在7.1.2中详细讨论。

Basically, a namespace prefix is distinguished by a pair of underscores in the function name, as in ns__getQuote where ns1 is the namespace prefix and getQuote is the remote method name. (A single underscore in an identifier name will be translated into a dash in XML, because dashes are more frequently used in XML compared to underscores, see Section 9.3.)

基本上，一个命名空间前缀是区别一对下划线的函数名，例如在ns__getQuote中ns是命名空间前缀和getQuote是远程方法。(一个单下划线标识符名称在XML中将被转换为破折号)，因为在XML破折号比下划线更频繁的使用。

 

The gSOAP compiler is invoked from the command line with:

这个gSOAP编译器被调用在命令行中:

 

soapcpp2 getQuote.

 

The compiler generates the stub routine for the getQuote remote method specified in the getQuote.h header file. 

这个编译器生成getQuote远程方法指定的stub程序在getQuote.h头文件中。

This stub routine can be called by a client program at any time to request a stock quote from the Delayed Stock Quote service. 

这个stub程序可以被客户端可以在任何时间调用，请求一个stock延迟的股票报价服务。

The interface to the generated stub routine is the following function prototype generated by the gSOAP compiler:

stub程序接口的生成是在以下函数原型中，通过gSOAP编译器生成的：

int soap call_ns1__getQuote(struct soap *soap, char *URL, char *action, char *symbol, float

&Result);

 

 

The stub routine is saved in soapClient.cpp. 

这个stub程序被保存在soapClient.cpp中。

The file soapC.cpp contains the serializer and deserializer routines for the data types used by the stub. 

这个soapC.cpp文件包数据类型的含序列化和反序列化程序在stub中被使用。

You can use option -c for the soapcpp2 compiler to generate pure C code.

你可以用选项-c为soapcpp2编译生成纯C代码。

Note that the parameters of the soap_call_ns1__getQuote function are identical to the ns1__getQuote function prototype with three additional input parameters: soap must be a valid pointer to a gSOAP runtime environment, URL is the SOAP Web service endpoint URL passed as a string, and action is a string that denotes the SOAP action required by the Web service. 

注意soap_call_ns1__getQuote函数的参数是和ns1__getQuote函数原型完全一样的，三个额外的输入参数：soap必须是有效的指针指向一个gSOAP运行时环境，URL是这个OAP Web service的端点通过字符串，action是一个字符串，它表示Web service请求SOAP action的指示。

Note that the XMethods Delayed Stock Quote service endpoint URL is http://66.28.98.121:9090/soap and the SOAP action required is "" (two quotes). 

注意这个XMethods延迟股票报价服务的端点URL是http://66.28.98.121:9090/soap和SOAP action请求""(双引号)。

You can change the endpoint and action dynamically. 

你可以动态地改变端点和action。

The endpoint and action are the second and third parameters of the soap_call_ns1__getQuote. 

这个端点和action是soap_call_ns1__getQuote的第二个和第三个参数。

When NULL, the values specified in the header file will be used. 

当为NULL时，这个在头文件中指定的值将被使用。

The following example mixed C/C++ client program invokes the stub to retrieve the latest IBM stock quote from the XMethods Delayed Stock Quote service:

下面的例子混合C/C++程序援引这个stub最取得最新的IBM股票从XMethods延迟股票报价服务：

 

#include "soapH.h" // obtain the generated stub

#include "net_DOT_xmethods_DOT_services_DOT_stockquote_DOT_StockQuoteBinding.nsmap"

// obtain the namespace mapping table

int main()

{

struct soap soap; // gSOAP runtime environment

 

float quote;

soap init(&soap); // initialize runtime environment (only once)

if (soap call ns1 getQuote(&soap, NULL, NULL, "IBM", "e) == SOAP OK)

std::cout << ”Current IBM Stock Quote = ” << quote << std::endl;

else // an error occurred

soap print fault(&soap, stderr); // display the SOAP fault message on the stderr stream

soap destroy(&soap); // delete deserialized class instances (for C++ only)

soap end(&soap); // remove deserialized data and clean up

soap done(&soap); // detach the gSOAP environment

return 0;

}

When successful, the stub returns SOAP_OK and quote contains the latest stock quote. 

当成功时，这个stub返回SOAP_OK和quot包含最近股票报价。

Otherwise, an error occurred and the SOAP fault is displayed with the soap_print_fault function.

否则，发生一个错误和SOAP显示错误用soap_print_fault 函数。

 

The gSOAP compiler also generates a proxy class for C++ client applications. 

这个gSOAP编译器也生成一个C++客户端应用的代理类。

This generated proxy class can be included into a client application together with the generated namespace table as shown in this example:

这个生成的代理类被包含在客户端程序一起用生成的命名空间表作为演示在这个例子中。

 

#include "soapnet_DOT_xmethods_DOT_services_DOT_stockquote_DOT_StockQuoteBindingProxy.h"

// get proxy

#include "net_DOT_xmethods_DOT_services_DOT_stockquote_DOT_StockQuoteBinding.nsmap"

// obtain the namespace mapping table

int main()

{

net q; // ”net” is the proxy class with a name that is the short name of the service

float r;

if (q.ns1__getQuote(”IBM”, r) == SOAP OK)

std::cout << r << std::endl;

else

soap print fault(q.soap, stderr);

return 0;

}

 

The proxy class constructor allocates and initializes a gSOAP environment for the instance. 

这个代理类构造函数分配和初始一个gSOAP环境的实例。

All the HTTP and SOAP/XML processing is hidden and performed on the background. 

所有的HTTP和SOAP/XML处理隐藏和后台执行。

Note that you can change the name of the service in the header file generated by the WSDL parser. 

注意你可以改变这个服务的名字在头文件，在WSDL解析器生成后的头文件中。

The name is extracted from the WSDL content and may not always be in a short format. 

这个名字充WSDL内容中提取和不可能总是一个短的格式。

Feel free to change the entry

随意更改入口

 

 

 

//gsoap ns1 service name: net DOT xmethods DOT services DOT stockquote DOT StockQuoteBinding to use a more suitable name. 

 

The name will control the file name of the proxy class file and the XML namespace mapping table.

这个名称将要控制这个proxy代理类的文件名和XML命名空间映射表。

The following functions can be used to explicitly setup a gSOAP runtime environment (struct soap):

以下的函数可以明确第安装一个gSOAP运行时环境(struct soap);

 

部分描述参考 gsoap-win32-2.7\doc\soapdoc2.html 中的内容

Function Description

soap_init(struct soap *soap) Initializes a runtime environment (required only once)

soap_init(struct soap *soap) 初始化运行时环境(必须仅一次)

soap_init1(struct soap *soap, soap_mode iomode) Initializes a runtime environment and set in/out mode flags

soap_init1(struct soap *soap, soap_mode iomode) 初始运行时环境和设置输入/输出模式标识

soap_init2(struct soap *soap, soap_mode imode, soap_mode omode) Initializes a runtime environment and set separate mode flags

soap_init2(struct soap *soap, soap_mode imode, soap_mode omode) 初始运行时环境和设置分离模式标识

struct soap *soap_new() Allocates, initializes, and returns a pointer to a runtime environment

struct soap *soap_new() 分配，初始化，和返回指针指向运行时环境

struct soap *soap_new1(soap_mode iomode) Allocates, initializes, and returns a pointer to a runtime environment and set in/out mode flags

struct soap *soap_new1(soap_mode iomode) 分配，初始化，和返回指针指向运行时环境和设置输入/输出模式标识

struct soap *soap_new2(soap_mode imode, soap_mode omode) Allocates, initializes, and returns a pointer to a runtime environment and set separate in/out mode flags

struct soap *soap_new2(soap_mode imode, soap_mode omode) 分配，初始化，和返回指针指向运行时环境和设置输入/输出模式标识和设置分离模式标识

struct soap *soap_copy(struct soap *soap) Allocates a new runtime environment and copies of the argument environment such that the new does not share data with the argument environment

struct soap *soap_copy(struct soap *soap) 分配一个新的运行时环境和拷贝参数环境，这样新的带参数环境不共享数据。

soap_done(struct soap *soap) Reset, close communications, and remove callbacks

soap_done(struct soap *soap) 重置，关闭通信，和移除回收

 

An environment can be reused as many times as necessary for client-side remote calls and does not need to be reinitialized in doing so. 

一个环境可以重新使用多次是一样的，客户端远程调用必要的，不必要去重新初始化。

A new environment is required for each new thread to guarantee exclusive access to runtime environments by threads.

一个新的环境是每个新的线程去保证排他访问所必须的，线程通过运行时环境。

Also the use of any client calls within an active service method requires a new environment.

也使用在任何客户端内部调用一个激活服务方法需要一个新的环境。

When the example client application is invoked, the SOAP request is performed by the stub routine soap_call_ns1__getQuote, which generates the following SOAP RPC request message:

当这个例子客户端程序被调用，这个SOAP请求是stub程序执行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>

 

The XMethods Delayed Stock Quote service responds with the SOAP response message:

这个XMethods延迟股票报价服务响应SOAP请求消息：

 

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>

 

The server’s SOAP RPC response is parsed by the stub.

这个服务的SOAP RPC响应是被stub解析的。

The stub routine further demarshalls the data of Result element of the SOAP response and stores it in the quote parameter of soap_call_ns1__getQuote.

这个stub程序进一步解组SOAP响应结果元素的数据和存储它在soap_call_ns1__getQuote的quot参数中。

A client program can invoke a remote method at any time and multiple times if necessary. 

一个客户端程序可以在任何时间和多次调用一个远程的方法。

Consider for example:

思考这个例子：

 

...

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], "es[i]) != SOAP OK)

break;

if (soap.error) // an error occurred

soap_print_fault(&soap, stderr);

soap_end(&soap); // clean up all deserialized data

...

 

This client composes an array of stock quotes by calling the ns1__getQuote stub routine for each

symbol in a portfolio array.

这个客户端组成一个股票报价数组通过调用ns1__getQuote stub程序遍历portfolio数组的元素。

This example demonstrated how easy it is to build a SOAP client with gSOAP once the details of

a Web service are available in the form of a WSDL document.

这个例子展示如何轻松构建一个SOAP客户端和用gSOAP的Web service详细，在可用的在WSDL文档中的形式。