wsaapi.c

一款开源的soap库

/*

wsaapi.c

WS-Addressing plugin for stand-alone services.

gSOAP XML Web services tools
Copyright (C) 2000-2006, Robert van Engelen, Genivia Inc., All Rights Reserved.
This part of the software is released under one of the following licenses:
GPL, the gSOAP public license, or Genivia's license for commercial use.
--------------------------------------------------------------------------------
gSOAP public license.

The contents of this file are subject to the gSOAP Public License Version 1.3
(the "License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.cs.fsu.edu/~engelen/soaplicense.html
Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
for the specific language governing rights and limitations under the License.

The Initial Developer of the Original Code is Robert A. van Engelen.
Copyright (C) 2000-2006, Robert van Engelen, Genivia Inc., All Rights Reserved.
--------------------------------------------------------------------------------
GPL license.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place, Suite 330, Boston, MA 02111-1307 USA

Author contact information:
[e-mail] / [e-mail]
--------------------------------------------------------------------------------
A commercial use license is available from Genivia, Inc., [e-mail]
--------------------------------------------------------------------------------
*/

/**

@mainpage

- @ref wsa documents the wsa plugin for WS-Addressing (2004 spec) support.

*/

/**

@page wsa The wsa plugin for stand-alone services

@section wsa_1 WS-Addressing Setup

The material in this section relates to the WS-Addressing specification 2004.

To use the wsa plugin:
-# 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.
-# Run soapcpp2 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 (assuming the wsa plugin is registered).
-# (Re-)compile stdsoap2.c/pp, dom.c/pp, wsaapi.c and the generated
   source files.
-# Use the wsa plugin API functions described below.

An example wsa client/server application can be found in samples/wsa.

To use WS-Addressing, the gSOAP header file for a service should declare a SOAP
Header with the required WS-Addressing information headers. The header file is
automatically generated by wsdl2h for a set of WSDLs. The gSOAP header file is
further processed by soapcpp2 to generate the binding codes.

The SOAP Header structure contains the WS-Addressing information headers
extracted from the WSDL and the WS-Addressing specification. For example:
@code
#import "soap12.h"
#import "wsa.h"

struct SOAP_ENV__Header
{
                 _wsa__MessageID  wsa__MessageID 0;
                 _wsa__RelatesTo *wsa__RelatesTo 0;
                 _wsa__From      *wsa__From      0;
  mustUnderstand _wsa__ReplyTo   *wsa__ReplyTo   0;
  mustUnderstand _wsa__FaultTo   *wsa__FaultTo   0;
  mustUnderstand _wsa__To         wsa__To        0;
  mustUnderstand _wsa__Action     wsa__Action    0;
};
@endcode

The SOAP Header struct is automatically generated by wsdl2h from a WSDL.
However, it must be manually defined when creating new services from gSOAP
header files. The gSOAP header file is processed with soapcpp2 to generate the
client-side and/or server-side binding code.

Note that the wsa.h header file in the import directory declares the
WS-Addressing information header elements and types. The soap12.h header
file enables SOAP 1.2 messaging. Note that the mustUnderstand qualifier
ensures that the information headers must be understood by a receiving SOAP
processor.

For developers: the WS-Addressing header blocks in wsa.h were generated from
the WS-Addressing schema with the wsdl2h tool and WS/WS-typemap.dat as follows:

@code
    $ wsdl2h -cegy -o wsa.h -t WS/WS-typemap.dat WS/WS-Addressing.xsd
@endcode

@section wsa_2 Client-side Usage

@subsection wsa_2_1 Formulating WS-Addressing Information Headers

To associate WS-Addressing information headers with service operations, the
SOAP Header struct must have been defined and for each service operation that
uses WS-Addressing method-header-part directives should be used in the gSOAP
header file of the service as follows:
@code
#import "wsa.h"

struct SOAP_ENV__Header { ... };

//gsoap ns service method-header-part: example wsa__MessageID
//gsoap ns service method-header-part: example wsa__RelatesTo
//gsoap ns service method-header-part: example wsa__From
//gsoap ns service method-header-part: example wsa__ReplyTo
//gsoap ns service method-header-part: example wsa__FaultTo
//gsoap ns service method-header-part: example wsa__To
//gsoap ns service method-header-part: example wsa__Action
//gsoap ns service method-action: example urn:example/examplePort/example
int ns__example(char *in, struct ns__exampleResponse *out);
@endcode

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 currenct soap struct context. An
optional source address information header can be added with
soap_wsa_add_From() (must be invoked after the soap_wsa_request call).

For example:
@code
soap_register_plugin(soap, soap_wsa);

soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction);
soap_wsa_add_From(soap, FromAddress); // optional: add a 'From' address

if (soap_call_ns__example(soap, ToAddress, NULL, ...))
  soap_print_fault(soap, stderr); // an error occurred
else
  // process the response 
@endcode

@subsection wsa_2_2 Information Headers for Relaying Server Responses

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.

For example:
@code
soap_register_plugin(soap, soap_wsa);

soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction);
soap_wsa_add_From(soap, FromAddress); // optional: add a 'From' address
soap_wsa_add_ReplyTo(soap, ReplyToAddress);

if (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
  if (soap->error == 202) // HTTP ACCEPTED
    printf("Request was accepted and results were forwarded\n");
  else
    soap_print_fault(soap, stderr); // an error occurred
}
else
  // error: for some reason the response was not relayed
@endcode

Note: the response message will be relayed when the From address is absent or
different than the ReplyTo address

@subsection wsa_2_3 Information Headers for Relaying Server Faults

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.

For example:
@code
soap_register_plugin(soap, soap_wsa);

soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction);
soap_wsa_add_From(soap, FromAddress); // optional: add a 'From' address
soap_wsa_add_FaultTo(soap, FaultToAddress);

if (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
  if (soap->error == 202) // HTTP ACCEPTED
    printf("A fault occurred and the fault details were forwarded\n");
  else
    soap_print_fault(soap, stderr); // a connection error occurred
}
else
  // process response 
@endcode

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_wsa_add_ReplyTo().

@section wsa_3 Server-side Usage

The wsa plugin should be registered with:
@code
soap_register_plugin(soap, soap_wsa);
@endcode

Once the plugin is registered, the soap_bind(), soap_accept(), and soap_serve() functions can be called to process requests.

Important: to dispatch service operations based on the WS-Addressing wsa:Action
information header, 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() 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.

For example:
@code
int ns__example(struct soap *soap, char *in, struct ns__exampleResponse *out)
{ if (soap_wsa_check(soap))
    return soap->error;
  // ... service logic
  return soap_wsa_reply(soap, ResponseMessageID, ResponseAction);
}
@endcode

To return a SOAP fault that is automatically relayed to a fault service based
on the FaultTo information header, the soap_wsa_sender_fault(),
soap_wsa_receiver_fault(), soap_wsa_sender_fault_subcode(), and
soap_wsa_receiver_fault_subcode() functions should be used instead of the
soap_sender_fault(), soap_receiver_fault(), soap_sender_fault_subcode(), and
soap_receiver_fault_subcode(), respectively.

For example:
@code
int ns__example(struct soap *soap, char *in, struct ns__exampleResponse *out)
{ if (soap_wsa_check(soap))
    return soap->error;
  // ... service logic
  // ... an error occurred, need to return fault possibly to fault service:
    return soap_wsa_sender_fault(soap, "Exception in service operation", NULL);
  // ... normal execution continues
  return soap_wsa_reply(soap, ResponseMessageID, ResponseAction);
}
@endcode

@section wsa_4 Implementing a Server for Handling ReplyTo Response Messages

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.

For example, suppose a service operation returns an exampleResponse message. We
declare the one-way exampleResponse operation as follows:
@code
#import "wsa.h"

struct SOAP_ENV__Header { ... };