The material in this section relates to the WS-Addressing specification.
To use the wsa plugin:
An example wsa client/server application can be found in
A gSOAP service definitions header file with a
#import "wsa.h" 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 wsaapi.h and wsaapi.c implement the WS-Addressing API described in this document.
A wsdl2h-generated service definitions header file might include the following imports:
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.
Note that the wsa.h, wsa3.h, wsa4.h, and wsa5.h 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.
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:
wsdl2h -cegy -o wsa.h -t WS/WS-typemap.dat WS/WS-Addressing.xsd
Refer to wsa.h for more details.
To associate WS-Addressing information headers with service operations, the SOAP Header struct
SOAP_ENV__Header 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:
Note that the use of wsa versions determines the wsa prefix, e.g. use
wsa5 for the latest WS-Addressing as in
In the client-side code, the WS-Addressing information headers are set with
soap_wsa_request 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
soap_wsa_add_From (must be invoked after the
To generate a UUID for the RequestMessageID, use:
To relay the response to another destination, the WS-Addressing ReplyTo information header is added with
soap_wsa_add_ReplyTo by passing a reply address URI string. The service returns "HTTP 202 ACCEPTED" to the client when the response message relay was successful.
Note: the response message will be relayed when the From address is absent or different than the ReplyTo address
To relay a server fault message to another destination, the WS-Addressing FaultTo information header is added with
soap_wsa_add_FaultTo by passing a relay address URI string. The service returns "HTTP 202 ACCEPTED" to the client when the fault was relayed.
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
SOAP and HTTP errors set the soap->error attribute, as shown in this example:
When a WS-Addressing error occurred, the wsa error code is stored in the SOAP Fault Subcode field. This information can be retrieved with:
When using wsa5.h, please refer to the standards and fault codes for this implementation. For the wsa5.h 2005/03 standard, several faults have an additional parameter (SOAP Fault detail):
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 headers (which are activated with an
#import "wsa5.h" in the header file for soapcpp2):
If your are using WS-Addressing 2004 (which is activated with an
#import "wsa.h" in the header file for soapcpp2) then change one line:
soap_wsse_set_wsu_id should only be set once. Each new call overrides the previous.
For more details on WS-Security, please see the WS-Security plugin documentation.
The wsa plugin should be registered with:
Once the plugin is registered, the
soap_serve functions can be called to process requests and semi-automatically handle the WS-Addressing header blocks.
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.
A service operation implementation should use
soap_wsa_check at the start of its execution 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
soap_wsa_reply with an optional message UUID string and a mandatory response action string. The response action string is documented in the wsdl2h-generated .h file for this service operation.
To return a SOAP fault that is automatically relayed to a fault service based on the FaultTo information header, the
soap_wsa_receiver_fault_subcode functions should be used instead of the usual
In case a Action must be associated with a SOAP Fault, use the
soap_wsa_receiver_fault_subcode_action functions to set the WS-Addressing Action (and HTTP SOAP Action header as well).
For example, the following service operation illustrates the use of
soap_wsa_check 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:
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
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
For example, suppose a service operation returns an exampleResponse message. We declare the one-way exampleResponse operation as follows:
Note that the action information is important, because it is used by the service dispatcher (assuming soapcpp2 option
-a is used).
The implementation in the server code uses soap_wsa_check() 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:
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.
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.
The fault operation in the WS-Addressing files (wsa5.h etc.) is declared as follows (here shown for the 2004/08 standard):
Because each service operation has a struct to hold its input parameters, we automatically generate the (original)
SOAP_ENV__Fault struct on the fly!
It is important to associate the wsa fault action with this operation as shown above.
The implementation of the Fault service operation in your server code should be similar to:
Note that SOAP 1.1 or SOAP 1.2 parameters are set based on the 1.1/1.2 messaging requirements.