diff options
| -rw-r--r-- | libcsoap/soap-env.h | 88 | ||||
| -rw-r--r-- | libcsoap/soap-fault.h | 7 | ||||
| -rw-r--r-- | libcsoap/soap-nhttp.h | 27 | ||||
| -rw-r--r-- | libcsoap/soap-service.h | 18 | ||||
| -rw-r--r-- | libcsoap/soap-wsil.h | 56 |
5 files changed, 187 insertions, 9 deletions
diff --git a/libcsoap/soap-env.h b/libcsoap/soap-env.h index 95867d7..d1c0d3e 100644 --- a/libcsoap/soap-env.h +++ b/libcsoap/soap-env.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-env.h,v 1.18 2006/11/25 15:06:57 m0gg Exp $ + * $Id: soap-env.h,v 1.19 2006/11/27 10:49:57 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -24,6 +24,92 @@ #ifndef __csoap_env_h #define __csoap_env_h +/** @file + * + * SOAP Envelope + * + * A SOAP message is an XML document that consists of a mandatory SOAP envelope, + * an optional SOAP header, and a mandatory SOAP body. This XML document is + * referred to as a SOAP message. The namespace identifier for the elements and + * attributes defined in this section is + * "http://schemas.xmlsoap.org/soap/envelope/". A SOAP message contains the + * following: + * - The Envelope is the top element of the XML document representing the + * message. + * - The Header is a generic mechanism for adding features to a SOAP message in a + * decentralized manner without prior agreement between the communicating + * parties. SOAP defines a few attributes that can be used to indicate who + * should deal with a feature and whether it is optional or mandatory. + * - The Body is a container for mandatory information intended for the ultimate + * recipient of the message. SOAP defines one element for the body, which is + * the Fault element used for reporting errors. + * + * The grammar rules are as follows: + * - Envelope + * -# The element name is "Envelope". + * -# The element MUST be present in a SOAP message + * -# The element MAY contain namespace declarations as well as additional + * attributes. If present, such additional attributes MUST be + * namespace-qualified. Similarly, the element MAY contain additional sub + * elements. If present these elements MUST be namespace-qualified and MUST + * follow the SOAP Body element. + * - Header + * -# The element name is "Header". + * -# The element MAY be present in a SOAP message. If present, the element MUST + * be the first immediate child element of a SOAP Envelope element. + * -# The element MAY contain a set of header entries each being an immediate + * child element of the SOAP Header element. All immediate child elements of + * the SOAP Header element MUST be namespace-qualified. + * - Body + * -# The element name is "Body". + * -# The element MUST be present in a SOAP message and MUST be an immediate + * child element of a SOAP Envelope element. It MUST directly follow the SOAP + * Header element if present. Otherwise it MUST be the first immediate child + * element of the SOAP Envelope element. + * -# The element MAY contain a set of body entries each being an immediate child + * element of the SOAP Body element. Immediate child elements of the SOAP Body + * element MAY be namespace-qualified. SOAP defines the SOAP Fault element, + * which is used to indicate error messages (see section 4.4). + * + * SOAP encodingStyle Attribute + * + * The SOAP encodingStyle global attribute can be used to indicate the + * serialization rules used in a SOAP message. This attribute MAY appear on any + * element, and is scoped to that element's contents and all child elements not + * themselves containing such an attribute, much as an XML namespace declaration + * is scoped. There is no default encoding defined for a SOAP message. + * + * The attribute value is an ordered list of one or more URIs identifying the + * serialization rule or rules that can be used to deserialize the SOAP message + * indicated in the order of most specific to least specific. Examples of values + * are: + * - "http://schemas.xmlsoap.org/soap/encoding/" + * - "http://my.host/encoding/restricted http://my.host/encoding/" + * - "" + * The serialization rules defined by SOAP are identified by the URI + * "http://schemas.xmlsoap.org/soap/encoding/". Messages using this particular + * serialization SHOULD indicate this using the SOAP encodingStyle attribute. In + * addition, all URIs syntactically beginning with + * "http://schemas.xmlsoap.org/soap/encoding/" indicate conformance with the SOAP + * encoding rules (though with potentially tighter rules added). A value of the + * zero-length URI ("") explicitly indicates that no claims are made for the + * encoding style of contained elements. This can be used to turn off any claims + * from containing elements. + * + * Envelope Versioning Model + * + * SOAP does not define a traditional versioning model based on major and minor + * version numbers. A SOAP message MUST have an Envelope element associated with + * the "http://schemas.xmlsoap.org/soap/envelope/" namespace. If a message is + * received by a SOAP application in which the SOAP Envelope element is + * associated with a different namespace, the application MUST treat this as a + * version error and discard the message. If the message is received through a + * request/response protocol such as HTTP, the application MUST respond with a + * SOAP VersionMismatch faultcode message using the SOAP + * "http://schemas.xmlsoap.org/soap/envelope/" namespace. + * + */ + /** * * The SOAP envelope namespace diff --git a/libcsoap/soap-fault.h b/libcsoap/soap-fault.h index 1a11365..8ced1c4 100644 --- a/libcsoap/soap-fault.h +++ b/libcsoap/soap-fault.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-fault.h,v 1.6 2006/11/21 20:59:02 m0gg Exp $ + * $Id: soap-fault.h,v 1.7 2006/11/27 10:49:57 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -24,7 +24,7 @@ #ifndef __csoap_fault_h #define __csoap_fault_h -/** +/** @file * * The SOAP Fault element is used to carry error and/or status information within * a SOAP message. If present, the SOAP Fault element MUST appear as a body entry @@ -59,6 +59,9 @@ * entries. Detailed error information belonging to header entries MUST be * carried within header entries. * + * @author F. Ayaz + * @version $Revision: 1.7 $ + * */ /** diff --git a/libcsoap/soap-nhttp.h b/libcsoap/soap-nhttp.h index ebf107d..2ce59e4 100644 --- a/libcsoap/soap-nhttp.h +++ b/libcsoap/soap-nhttp.h @@ -1,5 +1,5 @@ /****************************************************************** -* $Id: soap-nhttp.h,v 1.3 2006/11/26 20:13:05 m0gg Exp $ +* $Id: soap-nhttp.h,v 1.4 2006/11/27 10:49:57 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2007 Heiko Ronsdorf @@ -24,6 +24,31 @@ #ifndef __soap_nhttp_h #define __soap_nhttp_h +/** @file + * + * Using SOAP in HTTP + * + * This section describes how to use SOAP within HTTP with or without using the + * HTTP Extension Framework. Binding SOAP to HTTP provides the advantage of being + * able to use the formalism and decentralized flexibility of SOAP with the rich + * feature set of HTTP. Carrying SOAP in HTTP does not mean that SOAP overrides + * existing semantics of HTTP but rather that the semantics of SOAP over HTTP + * maps naturally to HTTP semantics. + * + * SOAP naturally follows the HTTP request/response message model providing SOAP + * request parameters in a HTTP request and SOAP response parameters in a HTTP + * response. Note, however, that SOAP intermediaries are NOT the same as HTTP + * intermediaries. That is, an HTTP intermediary addressed with the HTTP + * Connection header field cannot be expected to inspect or process the SOAP + * entity body carried in the HTTP request. + * + * HTTP applications MUST use the media type "text/xml" according to RFC 2376 + * when including SOAP entity bodies in HTTP messages. + * + * @see http://www.ietf.org/rfc/rfc2376.txt + * + */ + #ifdef __cplusplus extern "C" { #endif diff --git a/libcsoap/soap-service.h b/libcsoap/soap-service.h index e999e2e..33d69f6 100644 --- a/libcsoap/soap-service.h +++ b/libcsoap/soap-service.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-service.h,v 1.8 2006/11/23 15:27:33 m0gg Exp $ + * $Id: soap-service.h,v 1.9 2006/11/27 10:49:57 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -24,6 +24,22 @@ #ifndef __csoap_service_h #define __csoap_service_h +/** @file + * + * A Web service is a software system designed to support interoperable + * machine-to-machine interaction over a network. It has an interface described + * in a machine-processable format (specifically WSDL). Other systems interact + * with the Web service in a manner prescribed by its description using SOAP + * messages, typically conveyed using HTTP with an XML serialization in + * conjunction with other Web-related standards. + * + * @see http://www.w3.org/TR/wslc/, + * http://www.w3.org/TR/wsdl, + * http://www.w3.org/TR/owl-ref/ + * + */ + + typedef herror_t (*SoapServiceFunc)(struct SoapCtx *request, struct SoapCtx *response); typedef struct _SoapService diff --git a/libcsoap/soap-wsil.h b/libcsoap/soap-wsil.h index 3acaf42..0eedf67 100644 --- a/libcsoap/soap-wsil.h +++ b/libcsoap/soap-wsil.h @@ -1,8 +1,8 @@ /****************************************************************** - * $Id: soap-wsil.h,v 1.1 2006/11/23 13:20:46 m0gg Exp $ + * $Id: soap-wsil.h,v 1.2 2006/11/27 10:49:57 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C - * Copyright (C) 2003 Ferhat Ayaz + * Copyright (C) 2006 H. Ronsdorf * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -19,11 +19,56 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. * - * Email: ferhatayaz@yahoo.com + * Email: hero@persua.de ******************************************************************/ #ifndef __csoap_wsil_h #define __csoap_wsil_h +/** @file + * + * WS-Inspection + * + * The WS-Inspection specification provides an XML format for assisting in the + * inspection of a site for available services and a set of rules for how + * inspection related information should be made available for consumption. A + * WS-Inspection document provides a means for aggregating references to + * pre-existing service description documents which have been authored in any + * number of formats. These inspection documents are then made available at the + * point-of-offering for the service as well as through references which may be + * placed within a content medium such as HTML. + * + * Specifications have been proposed to describe Web Services at different levels + * and from various perspectives. It is the goal of the proposed Web Services + * Description Language (WSDL) to describe services at a functional level. The + * Universal Description, Discovery, and Integration (UDDI) schema aims at + * providing a more business-centric perspective. What has not yet been provided + * by these proposed standards is the ability to tie together, at the point of + * offering for a service, these various sources of information in a manner which + * is both simple to create and use. the WS-Inspection specification addresses + * this need by defining an XML grammar which facilitates the aggregation of + * references to different types of service description documents, and then + * provides a well defined pattern of usage for instances of this grammar. By + * doing this, the WS-Inspection specification provides a means by which to + * inspect sites for service offerings. + * + * Repositories already exist where descriptive information about Web services + * has been gathered together. The WS-Inspection specification provides + * mechanisms with which these existing repositories can be referenced and + * utilized, so that the information contained in them need not be duplicated if + * such a duplication is not desired. + * + * @author H. Ronsorf + * @version $Revision: 1.2 $ + * + * @see http://www-128.ibm.com/developerworks/library/specification/ws-wsilspec/ + * + */ + +/** + * + * Commandline argument to enabled automatic WSIL generation. + * + */ #define CSOAP_ENABLE_WSIL "-CSOAPwsil" #ifdef __cplusplus @@ -32,13 +77,16 @@ extern "C" { /** * - * Initializes the WSIL HTTP interface with commandline arguments. + * Initializes the WSIL HTTP interface with commandline arguments. The generated + * WSIL document can be seen at http://servername/inspection.wsil. * * @param argc commandline arg count * @param argv commandline arg vector * * @returns H_OK on success * + * @see CSOAP_ENABLE_WSIL + * */ extern herror_t soap_wsil_init_args(int argc, char *argv[]); |