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

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

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

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

 

7.2.1 Example

7.2.1 例子

The following example specifies three remote methods to be implemented by a new SOAP Web service:

下面的例子指定三个远程方法通过一个新的SOAP Web service实现：

 

// Contents of file ”calc.h”:

typedef double xsd__double;

int ns__add(xsd__double a, xsd__double b, xsd__double &result);

int ns__sub(xsd__double a, xsd__double b, xsd__double &result);

int ns__sqrt(xsd__double a, xsd__double &result);

 

The add and sub methods are intended to add and subtract two double floating point numbers stored in input parameters a and b and should return the result of the operation in the result output parameter. 

这个add和sub方法是打算去加和减两个浮点数，输入参数a和b将返回操作结果在result输出参数中。

The qsrt method is intended to take the square root of input parameter a and to return the result in the output parameter result. 

这个sqrt方法是打算获得输入参数a的平方根和返回操作结果在输出参数result中。

The xsd__double type is recognized by the gSOAP compiler as the xsd:double XSD Schema data type. 

这个xsd__double类型被gSOAP编译识别为XSD数据类型的xsd:double。

The use of typedef is a convenient way to associate primitive C types with primitive XML Schema data types.

使用typedef是一种方便的方法去关联原始C类型和原始XML Schema数据类型。

To generate the skeleton routines, the gSOAP compiler is invoked from the command line with:

去生成skeleton程序，这个gSOAP编译器被调用在命令行中：

 

soapcpp2 calc.h

 

 

The compiler generates the skeleton routines for the add, sub, and sqrt remote methods specified in the calc.h header file. 

这个编译器成skeletona程序，在calc.h头文件中指定用于add，sub，和sqrt的远程方法。

The skeleton routines are respectively, soap_serve_ns__add, soap_serve_ns__sub, and soap_serve_ns__sqrt and saved in the file soapServer.cpp. 

这个skeleton程序是分别是soap_serve_ns__add，soap_serve_ns__sub和soap_serve_ns__sqrt被保存在soapServer.cpp文件中。

The generated file soapC.cpp contains serializers and deserializers for the skeleton. 

这个生成的soapC.cpp 文件包含序列化和反序列化的skeleton。

The compiler also generates a service dispatcher:

这个编译器也生成一个服务调度：

the soap_serve function handles client requests on the standard input stream and dispatches the remote method requests to the appropriate skeletons to serve the requests. 

这个soap_serve函数处理标准的输入流的客户端请求和调度远程方法请求到适当的skeleton的服务请求。

The skeleton in turn calls the remote method implementation function. 

这个skeleton在返回远程方法实现功能。

The function prototype of the remote method implementation function is specified in the header file that is input to the gSOAP compiler.

这个远程方法函数原型实现的功能是指定输入头文件到gSOAP编译器。

 

Here is an example Calculator service application that uses the generated soap_serve routine to handle client requests:

这里是一个例子计算服务程序，使用生成的soap_serve程序去处理客户端请求：

 

// Contents of file ”calc.cpp”:

#include ”soapH.h”

#include <math.h> // for sqrt()

main()

{

soap_serve(soap_new()); // use the remote method request dispatcher

}

// Implementation of the ”add” remote method:

int ns__add(struct soap *soap, double a, double b, double &result)

{

result = a + b;

return SOAP_OK;

}

// Implementation of the ”sub” remote method:

int ns__sub(struct soap *soap, double a, double b, double &result)

{

result = a - b;

return SOAP_OK;

}

// Implementation of the ”sqrt” remote method:

int ns__sqrt(struct soap *soap, double a, double &result)

{

if (a >= 0)

{

result = sqrt(a);

return SOAP_OK;

}

else

return soap_receiver_fault(soap, ”Square root of negative number”, ”I can only take the square

root of a non-negative number”);

}

// As always, a namespace mapping table is needed:

struct Namespace namespaces[] =

{ // {”ns-prefix”, ”ns-name”}

{”SOAP-ENV”, ”http://schemas.xmlsoap.org/soap/envelope/”},

{”SOAP-ENC”, ”http://schemas.xmlsoap.org/soap/encoding/”},

{”xsi”, ”http://www.w3.org/2001/XMLSchema-instance”},

{”xsd”, ”http://www.w3.org/2001/XMLSchema”},

{”ns”, ”urn:simple-calc”}, // bind ”ns” namespace prefix

{NULL, NULL}

};

 

Note that the remote methods have an extra input parameter which is a pointer to the gSOAP runtime environment. 

注意这个远程方法有一个额外的输入参数，它是一个指针指向gSOAP运行时环境。

The implementation of the remote methods MUST return a SOAP error code. 

这个远程方法必须实现返回一个SOAP error代码。

The code SOAP_OK denotes success, while SOAP_FAULT denotes an exception with details that can be defined by the user. 

这个代码SOAP_OK表示成，然而SOAP_FALT表示异常，可以被用户定义详细。

The exception description can be assigned to the soap->fault->faultstring string and details can be assigned to the soap->fault->detail string. 

这个异常描述可以是赋值到soap->fault->faultstring字符串和详细可以是赋值到soap->fault->detail字符串。

This is SOAP 1.1 specific. 

这是SOAP 1.1明确的。

SOAP 1.2 requires the soap->fault->SOAP_ENV__Reason and the soap->fault->SOAP_ENV__Detail strings to be assigned. 

SOAP 1.2要求赋值到soap->fault->SOAP_ENV__Reason和soap->fault->SOAP_ENV__Detail字符串。

Better is to use the soap_receiver_fault function that allocates a fault struct and sets the SOAP Fault string and details regardless of the SOAP 1.1 or SOAP 1.2 version used. 

更好方法是使用soap_receiver_fault函数，分配一个fault结构体和设置SOAP错误字符串和详细的不管SOAP 1.1或 SOAP 1.2版本都能用。

The soap_receiver_fault function returns SOAP_FAULT, i.e. an application-specific fault. 

这个soap_receiver_fault函数返回SOAP_FAULT，即一个应用程序特定的错误。

The fault exception will be passed on to the client of this service.

这个错误异常将传递到客户端的服务。

This service application can be readily installed as a CGI application. 

这个服务应用程序可以容易地安装一个CGI程序。

The service description would be:

这个服务描述将是：

 

Endpoint URL: the URL of the CGI application

SOAP action: ”” (2 quotes)

Remote method namespace: urn:simple-calc

Remote method name: add

Input parameters: a of type xsd:double and b of type xsd:double

Output parameter: result of type xsd:double

Remote method name: sub

Input parameters: a of type xsd:double and b of type xsd:double

Output parameter: result of type xsd:double

Remote method name: sqrt

Input parameter: a of type xsd:double

Output parameter: result of type xsd:double or a SOAP Fault

 

The soapcpp2 compile generates a WSDL file for this service, see Section 7.2.8.

这个soapcpp2编译器生成这个服务的一个WSDL文件，请看7.2.8部分。

Unless the CGI application inspects and checks the environment variable SOAPAction which contains the SOAP action request by a client, the SOAP action is ignored by the CGI application. 

除非这个CGI应用程序检查和检查这个环境变量SOAPAction，包含一个客户端的SOAP动作请求，这个SOAP动作是被CGI应用程序忽略。

SOAP actions are specific to the SOAP protocol and provide a means for routing requests and for security reasons (e.g. firewall software can inspect SOAP action headers to grant or deny the SOAP request. Note that this requires the SOAP service to check the SOAP action header as well to match it with the remote method.)

SOAP动作是特定的SOAP协议和提供按某路线发送的请求的安全理由(例如，防火墙软件可以检查SOAP动作头文件授权或据金额SOAP请求。注意这需要SOAP服务去检查SOAP动作头文件还有匹配它的远程方法。)

The header file input to the gSOAP compiler does not need to be modified to generate client stubs for accessing this service. 

这个头文件输入到gSOAP编译器不需要修改去生成访问这个服务的客户端stubs。

Client applications can be developed by using the same header file as for which the service application was developed. 

作为这个服务应用程序的开发，客户端应用程序可以使用相同的头文件开发。

For example, the soap_call_ns__add stub routine is available from the soapClient.cpp file after invoking the gSOAP compiler on the calc.h header file. 

例如，这个soap_call_ns__add stub程序是可用soapClient.cpp文件在之后调用gSOAP编译器的calc.h头文件。

As a result, client and service applications can be developed without the need to know the details of the SOAP encoding used.

其结果是，客户端和服务端应用程序可以开发不需要知道详细的SOAP使用的编码。