gsoap中文文档（8.1.7~8.1.15）

 
　　8.1.7 如何改变回传元素的名称
　　SOAP返回消息重的元素命名没有固定的方式，但是推荐使用方法名加Response结尾。例如，getQuote方法的返回参数为getQuoteResponse。
　　返回参数的名称可以在头文件中以类或结构体的方式声明。这个类或结构体的名字就是服务返回参数的名字。因此，远程方法的输出参数必须声明为类或结构体的一个（多个）字段。gSOAP预编译器可以自动生成用于存根例程使用的结构体或类。
　　8.1.8 例子
　　我们将getQuote远程方法的返回参数做如下的改变：
　　// Contents of "getQuote.h":
　　typedef char *xsd__string;
　　typedef float xsd__float;
　　struct ns1__getQuoteResponse {xsd__float Result;};
　　int ns1__getQuote(xsd__string symbol, struct ns1__getQuoteResponse &r);
　　输入参数还是和原来一样的:
　　...
　　
　　 IBM
　　
　　
　　...
　　不同的是输出参数必须符合getQuoteResponse的名称并有同样的命名空间:
　　...
　　
　　
　　 41.81
　　
　　
　　...
　　类或结构体的定义也可以在函数内部进行，如:
　　// Contents of "getQuote.h":
　　typedef char *xsd__string;
　　typedef float xsd__float;
　　int ns1__getQuote(xsd__string symbol, struct ns1__getQuoteResponse {xsd__float Result;} &r);
　　8.1.9 如何指定多个输出参数
　　gSOAP预编译器将远程方法的最后一个参数作为输出参数，其余的参数都作为输入参数。如果要使用多个输出参数，就必须将输出参数定义为结构或类的形式。
　　8.1.10 例子
　　下面的例子中，getNames函数有个SSN作为输入参数，还有两个输出参数first及last。这个函数可以如下定义：
　　// Contents of file "getNames.h":
　　int ns3__getNames(char *SSN, struct ns3__getNamesResponse {char *first; char *last;} &r);
　　gSOAP将按照上述信息生成函数soap_call_ns3__getNames. 其请求信息为:
　　...
　　
　　...
　　
　　 999 99 9999
　　
　　...
　　输出信息为:
　　...
　　
　　 John
　　 Doe
　　
　　...
　　其中frist及last是远程方法的两个输出参数。
　　如果使用同一个变量作为输入、输出参数，也可以用结构体来定义。看下面的例子：
　　// Content of file "copy.h":
　　int X_rox__copy_name(char *name, struct X_rox__copy_nameResponse {char *name;} &r);
　　用类或结构体来定义为返回值，就可以定义上述输入、输出参数相同的远程方法。
　　gSOAP生成的请求信息如下：
　　...
　　
　　...
　　
　　 SOAP
　　
　　...
　　返回信息如下:
　　...
　　
　　 SOAP
　　
　　...
　　8.1.11 如何将输出参数定义为类和结构体类型
　　如果远程方法唯一的返回参数使用类或结构体等复杂的数据类型，就必须在调用远程方法时使用类或结构作为返回元素。
　　8.1.12 例子
　　下面举个例子来说明一下。Flighttracker服务提供实时的航班信息。该服务需要一个航班代码及飞行号码作为输入参数。远程方法名字为getFlightInfo，它包含两个字符串参数：航班代码，飞行号码。这两个参数都必须用xsd:string编码作为参数类型。该远程方法返回一个getFlightResponse元素，其中包含一个复杂数据类型FlightInfo。FlightInfo类型在头文件中以类方式定义，他的字段信息与FlightInfo类型中的字段相同。
　　// Contents of file "flight.h":
　　typedef char *xsd__string;
　　class ns2__FlightInfo
　　{
　　public:
　　xsd__string airline;
　　xsd__string flightNumber;
　　xsd__string altitude;
　　xsd__string currentLocation;
　　xsd__string equipment;
　　xsd__string speed;
　　};
　　struct ns1__getFlightInfoResponse {ns2__FlightInfo return_;};
　　int ns1__getFlightInfo(xsd__string param1, xsd__string param2, struct ns1__getFlightInfoResponse &r);
　　返回元素ns1__getFlightInfoResponse中包含一个ns2__FlightInfo类型的字段return_。该字段以_结尾，以便和return关键字分别。详细信息请参看10.3节：将C++标识符转换为XML元素名。
　　gSOAP预编译器生成soap_call_ns1__getFlightInfo代理类。下面是一个客户端使用这个代理类的例子：
　　struct soap soap;
　　...
　　soap_init(&soap);
　　...
　　soap_call_ns1__getFlightInfo(&soap, "testvger.objectspace.com/soap/servlet/rpcrouter",
　　"urn:galdemo:flighttracker", "UAL", "184", r);
　　...
　　struct Namespace namespaces[] =
　　{
　　{"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"},
　　{"ns1", "urn:galdemo:flighttracker"},
　　{"ns2", "http://galdemo.flighttracker.com"},
　　{NULL, NULL}
　　};
　　客户端执行时，代理类生成如下请求信息:
　　POST /soap/servlet/rpcrouter HTTP/1.1
　　Host: testvger.objectspace.com
　　Content-Type: text/xml
　　Content-Length: 634
　　SOAPAction: "urn:galdemo:flighttracker"
　　
　　 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:galdemo:flighttracker"
xmlns:ns2="http://galdemo.flighttracker.com"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">　　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:galdemo:flighttracker"
　　xmlns:ns2="http://galdemo.flighttracker.com"
　　SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
　　
　　
　　 UAL
　　 184
　　
　　
　　
　　Flighttracker服务返回:
　　HTTP/1.1 200 ok
　　Date: Thu, 30 Aug 2001 00:34:17 GMT
　　Server: IBM_HTTP_Server/1.3.12.3 Apache/1.3.12 (Win32)
　　Set-Cookie: sesessionid=2GFVTOGC30D0LGRGU2L4HFA;Path=/
　　Cache-Control: no-cache="set-cookie,set-cookie2"
　　Expires: Thu, 01 Dec 1994 16:00:00 GMT
　　Content-Length: 861
　　Content-Type: text/xml; charset=utf-8
　　Content-Language: en
　　
　　 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">　　xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
　　xmlns:xsd="http://www.w3.org/2001/XMLSchema">
　　
　　 SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">　　SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
　　
　　 A320
　　 UAL
　　 188 mi W of Lincoln, NE
　　 37000
　　 497
　　 184
　　
　　
　　
　　
　　代理类使用ns1__getFlightInfoResponse结构变量r来返回信息：
　　cout < 　　typedef char *xsd__string;
　　typedef float xsd__float;
　　int ns1__getQuote(xsd__string, xsd__float&);
　　要让参数名称在接收端匿名，在头文件定义函数时，参数名应该以下划线(_)开始。举个例子:
　　// Contents of "getQuote.h":
　　typedef char *xsd__string;
　　typedef float xsd__float;
　　int ns1__getQuote(xsd__string symbol, xsd__float &_return);
　　或者用一个结构体返回信息:
　　// Contents of "getQuote.h":
　　typedef char *xsd__string;
　　typedef float xsd__float;
　　struct ns1__getQuoteResponse {xsd__float _return;};
　　int ns1__getQuote(xsd__string symbol, struct ns1__getQuoteResponse &r);
　　在这个例子中，_return是个匿名输出参数。当服务回应该请求时，就可以使用任意的输出参数名称。输入参数名也可以是匿名的。这将影响web服务在gSOAP中的实现以及服务中参数名称的对应关系。
　　如果使用匿名参数，则函数定义中的参数顺序必须与所调用服务的参数顺序保持一致。
　　8.1.14 如何定义没有输入参数的方法
　　要定义一个没有输入参数的方法，只需要在函数定义中只保留一个参数作为输出参数就可以了。但是，某些C/C++编译器不能够编译空结构体（该结构体是gSOAP生成存储SOAP请求信息用）。这样，我们指定一个输入参数，使其类型为void*（gSOAP不能序列化void* 数据）。举个例子：
　　struct ns3__SOAPService
　　{
　　public:
　　int ID;
　　char *name;
　　char *owner;
　　char *description;
　　char *homepageURL;
　　char *endpoint;
　　char *SOAPAction;
　　char *methodNamespaceURI;
　　char *serviceStatus;
　　char *methodName;
　　char *dateCreated;
　　char *downloadURL;
　　char *wsdlURL;
　　char *instructions;
　　char *contactEmail;
　　char *serverImplementation;
　　};
　　struct ArrayOfSOAPService {struct ns3__SOAPService *__ptr; int __size;};
　　int ns__getAllSOAPServices(void *_, struct ArrayOfSOAPService &_return);
　　ns__getAllSOAPServices 方法包含一个void*类型的输入参数，它不会被gSOAP做序列化处理。多数的C/C++编译器允许空的结构体，所以void*类型的参数就不必使用了。
　　8.1.15 如何定义没有输出参数的方法
　　要指定一个没有输出参数的方法，需要将输出参数类型定义为一个空的结构体指针。
　　enum ns__event { off, on, stand_by };
　　int ns__signal(enum ns__event in, struct ns__signalResponse { } *out);
　　因为输出结构体为空，所以就没有输出参数了。如果编译器不支持空结构体，就指定一个包含void*类型变量的结构体。
　　有些SOAP资源用空的输出参数作为单向SOAP消息使用。但是，我们使用异步调用方式来支持单向消息。我们将在8.3节中详细讨论。
　　
本文转自
http://blog.csdn.net/lithe/archive/2006/04/17/666940.aspx