<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>gSOAP WS-Discovery: The wsa plugin for client applications and stand-alone services</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.4 -->
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">gSOAP WS-Discovery <span id="projectnumber">2.8 Stable</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">The wsa plugin for client applications and stand-alone services </div> </div>
</div>
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="wsa_1"></a>
WS-Addressing Setup</h2>
<p>The material in this section relates to the WS-Addressing specification.</p>
<p>To use the wsa plugin:</p>
<ol type="1">
<li>Run wsdl2h -t typemap.dat on a WSDL of a service that requires WS-Addressing headers. The typemap.dat file included in the gSOAP package is used to recognize and translate Addressing header blocks.</li>
<li>Run soapcpp2 -a on the header file produced by wsdl2h. To enable addressing-based service operation selection, you MUST use soapcpp2 option -a. This allows the service to dispatch methods based on the WS-Addressing action information header value (when the wsa plugin is registered).</li>
<li>(Re-)compile and link stdsoap2.c/pp or libgsoap, (dom.c/pp when needed), <a class="el" href="wsaapi_8c.html">wsaapi.c</a> and the soapcpp2-generated source files.</li>
<li>Use the wsa plugin API functions described below.</li>
</ol>
<p>An example wsa client/server application can be found in samples/wsa.</p>
<p>A gSOAP service definitions header file with a "wsa import" to support WS-Addressing is automatically generated by wsdl2h for a set of WSDLs that use WS-Addressing. The wsdl2h-generated header file should be further processed by soapcpp2 to generate the binding code. The <a class="el" href="wsaapi_8h.html">wsaapi.h</a> and <a class="el" href="wsaapi_8c.html">wsaapi.c</a> implement the WS-Addressing API described in this document.</p>
<p>A wsdl2h-generated service definitions header file might include the following imports:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#import "soap12.h"</span>
<span class="preprocessor">#import "wsa.h"</span> <span class="comment">// or wsa3.h (2003/03), wsa4.h (2004/03), wsa5.h (2005/03)</span>
</pre></div><p>The wsa.h header file is imported from import/wsa.h when soapcpp2 is run on this file. The wsa.h import can be manually added to enable WS-Addressing when needed. The gSOAP service definitions header file is processed with soapcpp2 to generate the client-side and/or server-side binding code.</p>
<p>Note that the wsa.h, wsa3.h, wsa4.h, and <a class="el" href="wsa5_8h.html">wsa5.h</a> header files are located in the import directory of the gSOAP package. These files define the WS-Addressing information header elements and types. The soap12.h header file enables SOAP 1.2 messaging.</p>
<p>For developers: the WS-Addressing header blocks in wsa.h (and others) were generated from the WS-Addressing schema with the wsdl2h tool and WS/WS-typemap.dat as follows:</p>
<div class="fragment"><pre class="fragment"> > wsdl2h -cegy -o wsa.h -t WS/WS-typemap.dat WS/WS-Addressing.xsd
</pre></div><p>Refer to wsa.h for more details.</p>
<h2><a class="anchor" id="wsa_2"></a>
Client-side Usage</h2>
<h3><a class="anchor" id="wsa_2_1"></a>
Constructing WS-Addressing Information Headers</h3>
<p>To associate WS-Addressing information headers with service operations, the SOAP Header struct <a class="el" href="struct_s_o_a_p___e_n_v_____header.html" title="Added.">SOAP_ENV__Header</a> must have been defined and for each service operation that uses WS-Addressing method-header-part directives should be used in the gSOAP service definitions header file as follows:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#import "wsa.h"</span>
<span class="comment">//gsoap ns service method-header-part: example wsa__MessageID</span>
<span class="comment">//gsoap ns service method-header-part: example wsa__RelatesTo</span>
<span class="comment">//gsoap ns service method-header-part: example wsa__From</span>
<span class="comment">//gsoap ns service method-header-part: example wsa__ReplyTo</span>
<span class="comment">//gsoap ns service method-header-part: example wsa__FaultTo</span>
<span class="comment">//gsoap ns service method-header-part: example wsa__To</span>
<span class="comment">//gsoap ns service method-header-part: example wsa__Action</span>
<span class="comment">//gsoap ns service method-action: example urn:example/examplePort/example</span>
<span class="keywordtype">int</span> ns__example(<span class="keywordtype">char</span> *in, <span class="keyword">struct</span> ns__exampleResponse *out);
</pre></div><p>Note that the use of wsa versions determines the wsa prefix, e.g. use wsa5 for the latest WS-Addressing as in wsa5__MessageID.</p>
<p>In the client-side code, the WS-Addressing information headers are set with <a class="el" href="wsaapi_8h.html#a3cbfe63b812df21c0bc2c8a129a1dc99" title="Sets the WS-Addressing information header for the next request message with MessageID (optional)...">soap_wsa_request()</a> by passing an optional message UUID string, a mandatory destination address URI string, and a mandatory request action URI string. The wsa plugin should be registered with the current soap struct context. An optional source address information header can be added with <a class="el" href="wsaapi_8h.html#a173c7beac1825c49f5d3b446ccdbc6b8" title="Sets WS-Addressing From header for request message.">soap_wsa_add_From()</a> (must be invoked after the soap_wsa_request call).</p>
<p>For example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include "<a class="code" href="wsaapi_8h.html">wsaapi.h</a>"</span>
soap_register_plugin(soap, <a class="code" href="wsaapi_8h.html#aa013e3760b97c2efcc71d29b57394501" title="Plugin registry function, used with soap_register_plugin.">soap_wsa</a>);
<span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a3cbfe63b812df21c0bc2c8a129a1dc99" title="Sets the WS-Addressing information header for the next request message with MessageID (optional)...">soap_wsa_request</a>(soap, RequestMessageID, ToAddress, RequestAction))
|| <a class="code" href="wsaapi_8h.html#a173c7beac1825c49f5d3b446ccdbc6b8" title="Sets WS-Addressing From header for request message.">soap_wsa_add_From</a>(soap, FromAddress)) <span class="comment">// optional: add a 'From' address</span>
... <span class="comment">// error: out of memory</span>
<span class="keywordflow">if</span> (soap_call_ns__example(soap, ToAddress, NULL, ...))
soap_print_fault(soap, stderr); <span class="comment">// an error occurred</span>
<span class="keywordflow">else</span>
<span class="comment">// process the response </span>
</pre></div><p>To generate a UUID for the RequestMessageID, use:</p>
<div class="fragment"><pre class="fragment"><span class="keyword">const</span> <span class="keywordtype">char</span> *RequestMessageID = <a class="code" href="wsaapi_8h.html#ac2b81c42093fc9fcadcf86e7d801e03b" title="Generates a random UUID (UUID algorithm version 4). Compile all source codes with -DWITH_OPENSSL for ...">soap_wsa_rand_uuid</a>(soap);
</pre></div><h3><a class="anchor" id="wsa_2_2"></a>
Information Headers for Relaying Server Responses</h3>
<p>To relay the response to another destination, the WS-Addressing ReplyTo information header is added with <a class="el" href="wsaapi_8h.html#a8b4871953a687b6f360b04c4bddeb49c" title="Sets WS-Addressing ReplyTo header for request message.">soap_wsa_add_ReplyTo()</a> by passing a reply address URI string. The service returns HTTP 202 ACCEPTED to the client when the response message relay was successful.</p>
<p>For example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include "<a class="code" href="wsaapi_8h.html">wsaapi.h</a>"</span>
soap_register_plugin(soap, <a class="code" href="wsaapi_8h.html#aa013e3760b97c2efcc71d29b57394501" title="Plugin registry function, used with soap_register_plugin.">soap_wsa</a>);
<span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a3cbfe63b812df21c0bc2c8a129a1dc99" title="Sets the WS-Addressing information header for the next request message with MessageID (optional)...">soap_wsa_request</a>(soap, RequestMessageID, ToAddress, RequestAction)
|| <a class="code" href="wsaapi_8h.html#a173c7beac1825c49f5d3b446ccdbc6b8" title="Sets WS-Addressing From header for request message.">soap_wsa_add_From</a>(soap, FromAddress) <span class="comment">// optional: add a 'From' address</span>
|| <a class="code" href="wsaapi_8h.html#a8b4871953a687b6f360b04c4bddeb49c" title="Sets WS-Addressing ReplyTo header for request message.">soap_wsa_add_ReplyTo</a>(soap, ReplyToAddress))
... <span class="comment">// error: out of memory</span>
<span class="keywordflow">if</span> (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
<span class="keywordflow">if</span> (soap->error == 202) <span class="comment">// HTTP ACCEPTED</span>
printf(<span class="stringliteral">"Request was accepted and results were forwarded\n"</span>);
<span class="keywordflow">else</span>
soap_print_fault(soap, stderr); <span class="comment">// an error occurred</span>
}
<span class="keywordflow">else</span>
<span class="comment">// unexpected OK: for some reason the response was not relayed</span>
</pre></div><p>Note: the response message will be relayed when the From address is absent or different than the ReplyTo address</p>
<h3><a class="anchor" id="wsa_2_3"></a>
Information Headers for Relaying Server Faults</h3>
<p>To relay a server fault message to another destination, the WS-Addressing FaultTo information header is added with <a class="el" href="wsaapi_8h.html#afc91d81e9eec6b9bc39efbd5e715a18a" title="Sets WS-Addressing FaultTo header for request message.">soap_wsa_add_FaultTo()</a> by passing a relay address URI string. The service returns HTTP 202 ACCEPTED to the client when the fault was relayed.</p>
<p>For example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include "<a class="code" href="wsaapi_8h.html">wsaapi.h</a>"</span>
soap_register_plugin(soap, <a class="code" href="wsaapi_8h.html#aa013e3760b97c2efcc71d29b57394501" title="Plugin registry function, used with soap_register_plugin.">soap_wsa</a>);
<span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a3cbfe63b812df21c0bc2c8a129a1dc99" title="Sets the WS-Addressing information header for the next request message with MessageID (optional)...">soap_wsa_request</a>(soap, RequestMessageID, ToAddress, RequestAction)
|| <a class="code" href="wsaapi_8h.html#a173c7beac1825c49f5d3b446ccdbc6b8" title="Sets WS-Addressing From header for request message.">soap_wsa_add_From</a>(soap, FromAddress) <span class="comment">// optional: add a 'From' address</span>
|| <a class="code" href="wsaapi_8h.html#afc91d81e9eec6b9bc39efbd5e715a18a" title="Sets WS-Addressing FaultTo header for request message.">soap_wsa_add_FaultTo</a>(soap, FaultToAddress))
... <span class="comment">// error: out of memory</span>
<span class="keywordflow">if</span> (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
<span class="keywordflow">if</span> (soap->error == 202) <span class="comment">// HTTP ACCEPTED</span>
printf(<span class="stringliteral">"A fault occurred and the fault details were forwarded\n"</span>);
<span class="keywordflow">else</span>
soap_print_fault(soap, stderr); <span class="comment">// a connection error occurred</span>
}
<span class="keywordflow">else</span>
<span class="comment">// process response </span>
</pre></div><p>Note that the call can still return a fault, such as a connection error when the service is not responding. In addition to the fault relay, the responses can be relayed with <a class="el" href="wsaapi_8h.html#a8b4871953a687b6f360b04c4bddeb49c" title="Sets WS-Addressing ReplyTo header for request message.">soap_wsa_add_ReplyTo()</a>.</p>
<h3><a class="anchor" id="wsa_2_4"></a>
Error Handling</h3>
<p>SOAP and HTTP errors set the soap->error attribute, as shown in this example:</p>
<div class="fragment"><pre class="fragment"><span class="keywordflow">if</span> (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
<span class="keywordflow">if</span> (soap->error == 202) <span class="comment">// HTTP ACCEPTED</span>
printf(<span class="stringliteral">"A fault occurred and the fault details were forwarded\n"</span>);
<span class="keywordflow">else</span>
soap_print_fault(soap, stderr); <span class="comment">// a connection error occurred</span>
}
<span class="keywordflow">else</span>
<span class="comment">// process response </span>
</pre></div><p>When a WS-Addressing error occurred, the wsa error code is stored in the SOAP Fault Subcode field. This information can be retrieved with:</p>
<div class="fragment"><pre class="fragment">wsa__FaultSubcodeValues fault;
<span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a4a67f22e5cb3659b0198c61a71f99fb0" title="Checks the presence of a WS-Addressing fault.">soap_wsa_check_fault</a>(soap, &fault))
{
<span class="keywordflow">switch</span> (fault)
{
<span class="keywordflow">case</span> wsa__InvalidMessageInformationHeader: ...
<span class="keywordflow">case</span> wsa__MessageInformationHeaderRequired: ...
<span class="keywordflow">case</span> wsa__DestinationUreachable: ...
<span class="keywordflow">case</span> wsa__ActionNotSupported: ...
<span class="keywordflow">case</span> wsa__EndpointUnavailable: ...
}
}
</pre></div><p>When using <a class="el" href="wsa5_8h.html">wsa5.h</a>, please refer to the standards and fault codes for this implementation. For the <a class="el" href="wsa5_8h.html">wsa5.h</a> 2005/03 standard, several faults have an additional parameter (SOAP Fault detail):</p>
<div class="fragment"><pre class="fragment"><a class="code" href="wsa5_8h.html#ae5ccb3ea0378299be007d022f1d3ef5a" title=""http://www.w3.org/2005/08/addressing":FaultCodesType is a simpleType restriction of xs:QName...">wsa5__FaultCodesType</a> fault;
<span class="keywordtype">char</span> *info;
<span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a4a67f22e5cb3659b0198c61a71f99fb0" title="Checks the presence of a WS-Addressing fault.">soap_wsa_check_fault</a>(soap, &fault, &info))
{
<span class="keywordflow">switch</span> (fault)
{
<span class="keywordflow">case</span> <a class="code" href="wsa5_8h.html#ae5ccb3ea0378299be007d022f1d3ef5aa9e6c5b22cdf5c37f9c8fed89725cfee3" title="xs:QName value=""http://www.w3.org/2005/08/addressing":InvalidAddressingHeader"">wsa5__InvalidAddressingHeader</a>:
<span class="keywordflow">if</span> (info)
printf(<span class="stringliteral">"The invalid addressing header element is %s\n"</span>, info);
...
}
}
</pre></div><h3><a class="anchor" id="wsa_2_5"></a>
Combining WS-Addressing with WS-Security</h3>
<p>WS-Security can be combined with WS-Addressing. To sign WS-Addressing header blocks, use the soap_wsse_set_wsu_id() WSSE-plugin call to set the wsu:Id attribute and signing of these attributed elements. For example, suppose we use WS-Addressing 2005:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include "<a class="code" href="wsaapi_8h.html">wsaapi.h</a>"</span>
<span class="preprocessor">#include "wsseapi.h"</span>
soap_register_plugin(soap, <a class="code" href="wsaapi_8h.html#aa013e3760b97c2efcc71d29b57394501" title="Plugin registry function, used with soap_register_plugin.">soap_wsa</a>);
soap_register_plugin(soap, soap_wsse);
soap_wsse_set_wsu_id(soap, <span class="stringliteral">"wsa5:From wsa5:To wsa5:ReplyTo wsa5:FaultTo wsa5:Action"</span>);
<span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a3cbfe63b812df21c0bc2c8a129a1dc99" title="Sets the WS-Addressing information header for the next request message with MessageID (optional)...">soap_wsa_request</a>(soap, RequestMessageID, ToAddress, RequestAction)
|| <a class="code" href="wsaapi_8h.html#a173c7beac1825c49f5d3b446ccdbc6b8" title="Sets WS-Addressing From header for request message.">soap_wsa_add_From</a>(soap, FromAddress) <span class="comment">// optional: add a 'From' address</span>
|| <a class="code" href="wsaapi_8h.html#afc91d81e9eec6b9bc39efbd5e715a18a" title="Sets WS-Addressing FaultTo header for request message.">soap_wsa_add_FaultTo</a>(soap, FaultToAddress))
... <span class="comment">// error: out of memory</span>
<span class="keywordflow">if</span> (soap_call_ns__example(soap, ToAddress, NULL, ...))
... <span class="comment">// error</span>
</pre></div><p>Note: soap_wsse_set_wsu_id() should only be set once. Each new call overrides the previous.</p>
<p>For more details on WS-Security, please see the <a href="../../wsse/html/index.html">WSSE plugin documentation</a>.</p>
<h2><a class="anchor" id="wsa_3"></a>
Server-side Usage</h2>
<p>The wsa plugin should be registered with:</p>
<div class="fragment"><pre class="fragment">soap_register_plugin(soap, <a class="code" href="wsaapi_8h.html#aa013e3760b97c2efcc71d29b57394501" title="Plugin registry function, used with soap_register_plugin.">soap_wsa</a>);
</pre></div><p>Once the plugin is registered, the soap_bind(), soap_accept(), and soap_serve() functions can be called to process requests and semi-automatically handle the WS-Addressing header blocks.</p>
<p>Important: to dispatch service operations based on the WS-Addressing wsa:Action information header, you must use soapcpp2 option -a. The generates a new dispatcher (in soapServer.c) based on the action value.</p>
<p>A service operation implementation should use <a class="el" href="wsaapi_8h.html#a35f9b1c46ea38b271b8d26bf8b051640" title="Checks the presence and validity of WS-Addressing information headers.">soap_wsa_check()</a> to verify the validity of the WS-Addressing information headers in the SOAP request message. To allow response message to be automatically relayed based on the ReplyTo information header, the service operation should return <a class="el" href="wsaapi_8h.html#a54fda97d2591acd5e2385cc110a50b30" title="Sets WS-Addressing header fields for server response. Automatically relays the response to the ReplyT...">soap_wsa_reply()</a> with an optional message UUID string and a mandatory response action string.</p>
<p>For example:</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> ns__example(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">char</span> *in, <span class="keyword">struct</span> ns__exampleResponse *out)
{ <span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a35f9b1c46ea38b271b8d26bf8b051640" title="Checks the presence and validity of WS-Addressing information headers.">soap_wsa_check</a>(soap))
<span class="keywordflow">return</span> soap->error;
<span class="comment">// ... service logic</span>
<span class="keywordflow">return</span> <a class="code" href="wsaapi_8h.html#a54fda97d2591acd5e2385cc110a50b30" title="Sets WS-Addressing header fields for server response. Automatically relays the response to the ReplyT...">soap_wsa_reply</a>(soap, ResponseMessageID, ResponseAction);
}
</pre></div><p>To return a SOAP fault that is automatically relayed to a fault service based on the FaultTo information header, the <a class="el" href="wsaapi_8h.html#a1e3eb7af78b1de680ac5352605afcd00" title="Sets sender SOAP Fault for server fault response.">soap_wsa_sender_fault()</a>, <a class="el" href="wsaapi_8h.html#ad53bf1b057c0facee6f4b94ab7d13045" title="Sets receiver SOAP Fault for server fault response.">soap_wsa_receiver_fault()</a>, <a class="el" href="wsaapi_8h.html#adfa72c8c9db6352acc80d7b2b771400c" title="Sets sender SOAP Fault (sub)code for server fault response.">soap_wsa_sender_fault_subcode()</a>, and <a class="el" href="wsaapi_8h.html#a8dfeadb13617174364cdd67c0bd18448" title="Sets receiver SOAP Fault (sub)code for server fault response.">soap_wsa_receiver_fault_subcode()</a> functions should be used instead of the usual soap_sender_fault(), soap_receiver_fault(), soap_sender_fault_subcode(), and soap_receiver_fault_subcode(), respectively. In case a Action must be associated with a SOAP Fault, use the <a class="el" href="wsaapi_8h.html#a049d60fd0b21da89b3f6889dd7c7192f" title="Sets sender SOAP Fault (sub)code for server fault response.">soap_wsa_sender_fault_subcode_action()</a> and <a class="el" href="wsaapi_8h.html#a2afdf00b160b0ac32d0cd413c4086df5" title="Sets receiver SOAP Fault (sub)code for server fault response.">soap_wsa_receiver_fault_subcode_action()</a> functions to set the WS-Addressing Action (and HTTP SOAP Action header as well).</p>
<p>For example, the following service operation illustrates the use of <a class="el" href="wsaapi_8h.html#a35f9b1c46ea38b271b8d26bf8b051640" title="Checks the presence and validity of WS-Addressing information headers.">soap_wsa_check()</a> to verify and process WS-Addressing header blocks and soap_wsA_reply() to enable responses to be relayed as per ReplyTo address in the WS-Addressing header:</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> ns__example(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">char</span> *in, <span class="keyword">struct</span> ns__exampleResponse *out)
{ <span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a35f9b1c46ea38b271b8d26bf8b051640" title="Checks the presence and validity of WS-Addressing information headers.">soap_wsa_check</a>(soap))
<span class="keywordflow">return</span> soap->error;
<span class="comment">// ... service logic</span>
<span class="comment">// ... an error occurred, need to return fault possibly to fault service:</span>
<span class="keywordflow">return</span> <a class="code" href="wsaapi_8h.html#a1e3eb7af78b1de680ac5352605afcd00" title="Sets sender SOAP Fault for server fault response.">soap_wsa_sender_fault</a>(soap, <span class="stringliteral">"Exception in service operation"</span>, NULL);
<span class="comment">// ... normal execution continues</span>
<span class="keywordflow">return</span> <a class="code" href="wsaapi_8h.html#a54fda97d2591acd5e2385cc110a50b30" title="Sets WS-Addressing header fields for server response. Automatically relays the response to the ReplyT...">soap_wsa_reply</a>(soap, ResponseMessageID, ResponseAction);
}
</pre></div><h2><a class="anchor" id="wsa_4"></a>
HTTPS Server-side Usage</h2>
<p>To enable HTTPS (SSL/TSL) servers, compile the sources with -DWITH_OPENSSL (and link with libgsoapssl, libssl, and libcrypto). Because WS-Addressing may relay messages over HTTPS as a sender (client), you must initialize the SSL context for server and client uses. Therefore, the context must have access to all the certificates need to verify the authenticity of the ReplyTo and FaultTo HTTPS servers. To do so, use the following SSL initialization before soap_bind():</p>
<div class="fragment"><pre class="fragment"><span class="keyword">struct </span>soap *soap = soap_new();
<span class="keywordflow">if</span> (soap_ssl_server_context(soap,
SOAP_SSL_DEFAULT,
<span class="stringliteral">"server.pem"</span>, <span class="comment">// the keyfile (server should authenticate)</span>
<span class="stringliteral">"password"</span>, <span class="comment">// password to read the key file</span>
<span class="stringliteral">"cacert.pem"</span>, <span class="comment">// cacert file to store trusted certificates (role as client)</span>
NULL, <span class="comment">// optional capath</span>
NULL, <span class="comment">// DH file name or DH param key len bits, when NULL use RSA</span>
NULL, <span class="comment">// file with random data to seed randomness</span>
<span class="stringliteral">"myserver"</span> <span class="comment">// unique server identification for SSL session cache</span>
))
{ soap_print_fault(soap, stderr);
...
}
soap->bind_flags = SO_REUSEADDR;
<span class="keywordflow">if</span> (!soap_valid_socket(soap_bind(soap, NULL, port, 100)))
{ soap_print_fault(soap, stderr);
...
}
</pre></div><h2><a class="anchor" id="wsa_5"></a>
Implementing a Server for Handling ReplyTo Response Messages</h2>
<p>To implement a separate server for handling relayed SOAP response messages based on the ReplyTo information header in the request message, the gSOAP header file should include a one-way service operation for the response message. These one-way response service operations are automatically generated with wsdl2h option -b.</p>
<p>For example, suppose a service operation returns an exampleResponse message. We declare the one-way exampleResponse operation as follows:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#import "wsa.h"</span>
<span class="comment">//gsoap ns service method-header-part: exampleResult wsa__MessageID</span>
<span class="comment">//gsoap ns service method-header-part: exampleResult wsa__RelatesTo</span>
<span class="comment">//gsoap ns service method-header-part: exampleResult wsa__From</span>
<span class="comment">//gsoap ns service method-header-part: exampleResult wsa__ReplyTo</span>
<span class="comment">//gsoap ns service method-header-part: exampleResult wsa__FaultTo</span>
<span class="comment">//gsoap ns service method-header-part: exampleResult wsa__To</span>
<span class="comment">//gsoap ns service method-header-part: exampleResult wsa__Action</span>
<span class="comment">//gsoap ns service method-action: exampleResult urn:example/examplePort/exampleResponse</span>
<span class="keywordtype">int</span> ns__exampleResponse(<span class="keywordtype">char</span> *out, <span class="keywordtype">void</span>);
</pre></div><p>Note that the action information is important, because it is used by the service dispatcher (assuming soapcpp2 option -a is used).</p>
<p>The implementation in the server code uses <a class="el" href="wsaapi_8h.html#a35f9b1c46ea38b271b8d26bf8b051640" title="Checks the presence and validity of WS-Addressing information headers.">soap_wsa_check()</a> to check the presense and validity of the WS-Addressing information header in the message. The soap_send_empty_response() function should be used to return an acknowledgment HTTP header with HTTP 202 ACCEPTED to the sender:</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> ns__exampleResponse(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">char</span> *out)
{ <span class="keywordflow">if</span> (<a class="code" href="wsaapi_8h.html#a35f9b1c46ea38b271b8d26bf8b051640" title="Checks the presence and validity of WS-Addressing information headers.">soap_wsa_check</a>(soap))
<span class="keywordflow">return</span> soap_send_empty_response(soap, 500); <span class="comment">// HTTP 500 Internal Server Error</span>
<span class="comment">// ... service logic</span>
<span class="keywordflow">return</span> soap_send_empty_response(soap, SOAP_OK); <span class="comment">// HTTP 202 ACCEPTED</span>
}
</pre></div><h2><a class="anchor" id="wsa_6"></a>
Implementing a Server for Handling FaultTo Fault Messages</h2>
<p>To implement a separate server for handling relayed SOAP fault messages based on the FaultTo information header in the request message, the gSOAP header file for soapcpp2 should include a SOAP fault service operation. This operation accepts fault messages that are relayed by other services.</p>
<p>Basically, we use a trick to generate the SOAP-ENV:Fault struct via a one-way service operation. This allows us both to implement a one-way service operation that accepts faults and to automatically generate the fault struct for fault data storage and manipulation.</p>
<p>The fault operation in the WS-Addressing files (<a class="el" href="wsa5_8h.html">wsa5.h</a> etc.) is declared as follows (here shown for the 2004/08 standard):</p>
<div class="fragment"><pre class="fragment"><span class="comment">//gsoap SOAP_ENV service method-action: Fault http://schemas.xmlsoap.org/ws/2004/08/addressing/fault</span>
<span class="keywordtype">int</span> <a class="code" href="wsa5_8h.html#af1f0af3d70354401b6969aa0b689a5dc">SOAP_ENV__Fault</a>
( _QName faultcode, <span class="comment">// SOAP 1.1</span>
<span class="keywordtype">char</span> *faultstring, <span class="comment">// SOAP 1.1</span>
<span class="keywordtype">char</span> *faultactor, <span class="comment">// SOAP 1.1</span>
<span class="keyword">struct</span> SOAP_ENV__Detail *detail, <span class="comment">// SOAP 1.1</span>
<span class="keyword">struct</span> SOAP_ENV__Code *SOAP_ENV__Code, <span class="comment">// SOAP 1.2</span>
<span class="keyword">struct</span> SOAP_ENV__Reason *SOAP_ENV__Reason, <span class="comment">// SOAP 1.2</span>
<span class="keywordtype">char</span> *SOAP_ENV__Node, <span class="comment">// SOAP 1.2</span>
<span class="keywordtype">char</span> *SOAP_ENV__Role, <span class="comment">// SOAP 1.2</span>
<span class="keyword">struct</span> SOAP_ENV__Detail *SOAP_ENV__Detail, <span class="comment">// SOAP 1.2</span>
<span class="keywordtype">void</span>
);
</pre></div><p>Because each service operation has a struct to hold its input parameters, we automatically generate the (original) SOAP_ENV__Fault struct on the fly!</p>
<p>It is important to associate the wsa fault action with this operation as shown above.</p>
<p>The implementation of the Fault service operation in your server code should be something like:</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> <a class="code" href="wsa5_8h.html#af1f0af3d70354401b6969aa0b689a5dc">SOAP_ENV__Fault</a>(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">char</span> *faultcode, <span class="keywordtype">char</span> *faultstring, <span class="keywordtype">char</span> *faultactor, <span class="keyword">struct</span> SOAP_ENV__Detail *detail, <span class="keyword">struct</span> SOAP_ENV__Code *SOAP_ENV__Code, <span class="keyword">struct</span> SOAP_ENV__Reason *SOAP_ENV__Reason, <span class="keywordtype">char</span> *SOAP_ENV__Node, <span class="keywordtype">char</span> *SOAP_ENV__Role, <span class="keyword">struct</span> SOAP_ENV__Detail *SOAP_ENV__Detail)
{
... = faultcode; <span class="comment">// SOAP 1.1 fault code string (QName)</span>
... = faultstring; <span class="comment">// SOAP 1.1 fault string</span>
... = faultactor; <span class="comment">// SOAP 1.1 fault actor string</span>
... = detail; <span class="comment">// SOAP 1.1 fault detail struct</span>
... = SOAP_ENV__Code; <span class="comment">// SOAP 1.2 fault code struct</span>
... = SOAP_ENV__Reason; <span class="comment">// SOAP 1.2 reason struct</span>
... = SOAP_ENV__Node; <span class="comment">// SOAP 1.2 node string</span>
... = SOAP_ENV__Role; <span class="comment">// SOAP 1.2 role string</span>
... = SOAP_ENV__Detail; <span class="comment">// SOAP 1.2 detail struct</span>
<span class="keywordflow">return</span> SOAP_OK;
}
</pre></div><p>Note that SOAP 1.1 or SOAP 1.2 parameters are set based on the 1.1/1.2 messaging requirements. </p>
</div></div>
<hr class="footer"/><address class="footer"><small>Generated on Sun Dec 9 2012 19:57:57 for gSOAP WS-Discovery by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
