/******************************************************************
* $Id: soap-env.h,v 1.21 2006/12/09 09:27:11 m0gg Exp $
*
* CSOAP Project: A SOAP client/server library in C
* Copyright (C) 2003 Ferhat Ayaz
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library 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
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*
* Email: ayaz@jprogrammer.net
******************************************************************/
#ifndef __csoap_env_h
#define __csoap_env_h
/** @file
*
* \section soap_env 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.
*
* \subsection soap_env_enc 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.
*
* \subsection soap_env_version 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
*
*/
static const char * const soap_env_ns = "http://schemas.xmlsoap.org/soap/envelope/";
/**
*
* The SOAP envelope object.
*
*/
struct SoapEnv
{
xmlNodePtr root; /** Pointer to the firts xml element (envelope) */
xmlNodePtr header;
xmlNodePtr body;
xmlNodePtr cur; /** Pointer to the current xml element. (stack) */
};
typedef void (*XmlSerializerCallback) (void * obj, const xmlChar *root_element_name, void (*OnStartElement) (const xmlChar * element_name, int attr_count, xmlChar ** keys, xmlChar ** values, void *userData), void (*OnCharacters) (const xmlChar * element_name, const xmlChar * chars, void *userData), void (*OnEndElement) (const xmlChar * element_name, void *userData), void *userdata);
#ifdef __cplusplus
extern "C" {
#endif
/**
*
* Creates an envelope with a fault object.
*
* @param faultcode The fault code @see fault_code_t
* @param faultstring A fault message
* @param faultactor The fault actor (This can be NULL)
* @param detail The detail of the error (This can be NULL)
* @param out the result envelope out parameter like follows
*
*
*
*
*
*
* ...
* ...
* ...
* ..
*
*
*
*
*
*
* @returns H_OK if success
*
* @see soap_fault_new
*
*/
extern herror_t soap_env_new_with_fault(int faultCode, const char *faultString, const char *faultActor, const char *detail, struct SoapEnv **out);
/**
*
* Creates an envelope with a method to invoke a soap service.
* Use this function to create a client call.
*
* @param urn The urn of the soap service to invoke
* @param method The method name of the soap service
*
* @param out the result envelope out parameter like follows
* @returns H_OK if success
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
extern herror_t soap_env_new_with_method(const char *urn, const char *method, struct SoapEnv ** out);
/**
*
* Creates a soap envelope with a response.
* Use this function to create a response envelope object
* for a request. This function is only relevant for soap
* service implementors.
*
* @see example csoap/simpleserver.c
*
* @param req The request object. A response object will be created
* to this request.
*
* @param out the result envelope out paramter like follows
* @returns H_OK if success
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
extern herror_t soap_env_new_with_response(struct SoapEnv * req, struct SoapEnv ** out);
/**
*
* Creates an envelope from a given libxml2 xmlDocPtr.
*
* @param doc the xml document pointer
* @param out the output envelope object
*
* @returns H_OK if success
*
*/
extern herror_t soap_env_new_from_doc(xmlDocPtr doc, struct SoapEnv ** out);
/**
*
* Create an envelop object from a string.
* The string must be in xml format.
*
* @param buffer The string to parse into a envelope.
* @param out the output envelope object
* @returns H_OK if success
*/
extern herror_t soap_env_new_from_buffer(const char *buffer, struct SoapEnv ** out);
/**
*
* Adds a new xml node under the current parent.
*
*
* [value]
*
*
* @param env The envelope object
* @param type Type of the parameter. Something like "xsd:string" or
* "xsd:int" or custom types.
* @param name Name of the xml node
* @param value Text value of the xml node
*
* @returns The added xmlNode pointer.
*
* @see tutorial
*
*/
extern xmlNodePtr soap_env_add_item(struct SoapEnv * env, const char *type, const char *name, const char *value);
/**
*
* Adds attachment href node to the envelope current parent.
*
*
*
*
*
* @param env The envelope object
* @param name Name of the xml node
* @param href href. A CID string filled by
* soap_ctx_add_attachment()
*
* @returns The added xmlNode pointer.
*
* @see soap_ctx_add_file tutorial
*/
extern xmlNodePtr
soap_env_add_attachment(struct SoapEnv * env, const char *name, const char *href);
/**
*
* Serialize and adds obj to the envelope.
* TODO: Document this function !
*
* Important:
*
*/
extern void soap_env_add_custom(struct SoapEnv * env, void *obj, XmlSerializerCallback cb, const char *type, const char *name);
/**
*
* Same as soap_env_add_item() with c style arguments
* like in printf(). "value" is the format string.
*
* Important: The totally length of value (incl. args)
* must be lower the 1054.
*
* @see soap_env_add_item
*/
extern xmlNodePtr
soap_env_add_itemf(struct SoapEnv * env, const char *type, const char *name, const char *value, ...);
/**
*
* Push the current xml node in the soap envelope one level
* deeper. Here an example:
*
*
* soap_env_push_item(env, "my:custom", "Person");
* soap_env_add_item(env, "xsd:string", "name", "Mickey");
* soap_env_add_item(env, "xsd:string", "lastname", "Mouse");
* soap_env_pop_item(env);
*
*
* This will create the xml like follows.
*
*
*
* Mickey
* Mouse
*
*
*
* @returns The added xmlNode pointer.
*
* @see tutorial
*
*/
extern xmlNodePtr soap_env_push_item(struct SoapEnv * env, const char *type, const char *name);
/**
*
* Sets the xml pointer 1 level higher.
*
* @param env The envelope object
*
* @see soap_env_push_item
*/
extern void soap_env_pop_item(struct SoapEnv * env);
/**
*
* Free the envelope.
*
* @param env The envelope object
*
*/
extern void soap_env_free(struct SoapEnv *env);
/**
*
* Gets the xml node pointing to SOAP Body.
*
*/
extern xmlNodePtr soap_env_get_body(struct SoapEnv * env);
/**
*
* Get the xml node pointing to SOAP method (call)
*
*/
extern xmlNodePtr soap_env_get_method(struct SoapEnv * env);
/**
*
* Get the xml node pointing to SOAP Fault
*
*/
extern xmlNodePtr soap_env_get_fault(struct SoapEnv * env);
/**
*
* Get the xml node pointing to SOAP Header
*
*/
extern xmlNodePtr soap_env_get_header(struct SoapEnv * env);
/**
*
* Get the URN of the message.
*
*/
extern const char *soap_env_find_urn(struct SoapEnv * env);
/**
*
* Get the method of the message.
*
*/
extern const char *soap_env_find_methodname(struct SoapEnv * env);
#ifdef __cplusplus
}
#endif
#endif