summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatar m0gg2006-11-27 10:49:57 +0000
committerGravatar m0gg2006-11-27 10:49:57 +0000
commit6778f81586ad6869de18ee7abd8e4940b02d37c4 (patch)
treebde9a4abd2398204b8be8490af91c721d9fbf192
parent65985c4e6527c82a75367d9c5418b009dfbc6379 (diff)
downloadcsoap-6778f81586ad6869de18ee7abd8e4940b02d37c4.tar.gz
csoap-6778f81586ad6869de18ee7abd8e4940b02d37c4.tar.bz2
Documentation enhancements
-rw-r--r--libcsoap/soap-env.h88
-rw-r--r--libcsoap/soap-fault.h7
-rw-r--r--libcsoap/soap-nhttp.h27
-rw-r--r--libcsoap/soap-service.h18
-rw-r--r--libcsoap/soap-wsil.h56
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[]);