soap-env.h File Reference

Go to the source code of this file.

Data Structures
struct	SoapEnv
Typedefs
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)
Functions
herror_t	soap_env_new_with_fault (int faultCode, const char *faultString, const char *faultActor, const char *detail, struct SoapEnv **out)
herror_t	soap_env_new_with_method (const char *urn, const char *method, struct SoapEnv **out)
herror_t	soap_env_new_with_response (struct SoapEnv *req, struct SoapEnv **out)
herror_t	soap_env_new_from_doc (xmlDocPtr doc, struct SoapEnv **out)
herror_t	soap_env_new_from_buffer (const char *buffer, struct SoapEnv **out)
xmlNodePtr	soap_env_add_item (struct SoapEnv *env, const char *type, const char *name, const char *value)
xmlNodePtr	soap_env_add_attachment (struct SoapEnv *env, const char *name, const char *href)
void	soap_env_add_custom (struct SoapEnv *env, void *obj, XmlSerializerCallback cb, const char *type, const char *name)
xmlNodePtr	soap_env_add_itemf (struct SoapEnv *env, const char *type, const char *name, const char *value,...)
xmlNodePtr	soap_env_push_item (struct SoapEnv *env, const char *type, const char *name)
void	soap_env_pop_item (struct SoapEnv *env)
void	soap_env_free (struct SoapEnv *env)
xmlNodePtr	soap_env_get_body (struct SoapEnv *env)
xmlNodePtr	soap_env_get_method (struct SoapEnv *env)
xmlNodePtr	soap_env_get_fault (struct SoapEnv *env)
xmlNodePtr	soap_env_get_header (struct SoapEnv *env)
const char *	soap_env_find_urn (struct SoapEnv *env)
const char *	soap_env_find_methodname (struct SoapEnv *env)

---

Detailed Description

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
  1. The element name is "Envelope".
  2. The element MUST be present in a SOAP message
  3. 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
  1. The element name is "Header".
  2. 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.
  3. 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
  1. The element name is "Body".
  2. 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.
  3. 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.

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.

---

Typedef Documentation

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)

---

Function Documentation

xmlNodePtr soap_env_add_attachment	(	struct SoapEnv *	env,
		const char *	name,
		const char *	href
	)

Adds attachment href node to the envelope current parent.

  <m:[name] href=[href]/>
 

Parameters:

	env	The envelope object
	name	Name of the xml node
	href	href. A CID string filled by soap_ctx_add_attachment()

Returns:

The added xmlNode pointer.

See also:

soap_ctx_add_file tutorial

void soap_env_add_custom	(	struct SoapEnv *	env,
		void *	obj,
		XmlSerializerCallback	cb,
		const char *	type,
		const char *	name
	)

Serialize and adds obj to the envelope. TODO: Document this function !
Important:

xmlNodePtr soap_env_add_item	(	struct SoapEnv *	env,
		const char *	type,
		const char *	name,
		const char *	value
	)

Adds a new xml node under the current parent.

  <m:[name] type=[type]>[value]</m:[name]>
 

Parameters:

	env	The envelope object
	type	Type of the parameter. Something like "xsd:string" or "xsd:int" or custom types.
	name	Name of the xml node
	value	Text value of the xml node

Returns:

The added xmlNode pointer.

See also:

tutorial

xmlNodePtr soap_env_add_itemf	(	struct SoapEnv *	env,
		const char *	type,
		const char *	name,
		const char *	value,
			...
	)

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 also:

soap_env_add_item

const char* soap_env_find_methodname

(

struct SoapEnv *

env

)

Get the method of the message.

const char* soap_env_find_urn

(

struct SoapEnv *

env

)

Get the URN of the message.

void soap_env_free

(

struct SoapEnv *

env

)

Free the envelope.

Parameters:

env

The envelope object

xmlNodePtr soap_env_get_body

(

struct SoapEnv *

env

)

Gets the xml node pointing to SOAP Body.

xmlNodePtr soap_env_get_fault

(

struct SoapEnv *

env

)

Get the xml node pointing to SOAP Fault

xmlNodePtr soap_env_get_header

(

struct SoapEnv *

env

)

Get the xml node pointing to SOAP Header

xmlNodePtr soap_env_get_method

(

struct SoapEnv *

env

)

Get the xml node pointing to SOAP method (call)

herror_t soap_env_new_from_buffer	(	const char *	buffer,
		struct SoapEnv **	out
	)

Create an envelop object from a string. The string must be in xml format.

Parameters:

	buffer	The string to parse into a envelope.
	out	the output envelope object

Returns:

H_OK if success

herror_t soap_env_new_from_doc	(	xmlDocPtr	doc,
		struct SoapEnv **	out
	)

Creates an envelope from a given libxml2 xmlDocPtr.

Parameters:

	doc	the xml document pointer
	out	the output envelope object

Returns:

H_OK if success

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 fault object.

Parameters:

faultcode

The fault code

See also:

fault_code_t

Parameters:

	faultstring	A fault message
	faultactor	The fault actor (This can be NULL)
	detail	The detail of the error (This can be NULL)
	out	the result envelope out parameter like follows

  <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..."
       xmlns:xsi="..."
     xmlns:xsd="...">
   <SOAP-ENV:Body>

	 <Fault>
	  <faultcode>...</faultcode>
	  <faultstring>...</faultstring>
	  <faultactor>...</faultactor>
	  <faultdetail>..</faultdetail>
	 </Fault>

   </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>
  

Returns:

H_OK if success

See also:

soap_fault_new

herror_t soap_env_new_with_method	(	const char *	urn,
		const char *	method,
		struct SoapEnv **	out
	)

Creates an envelope with a method to invoke a soap service. Use this function to create a client call.

Parameters:

	urn	The urn of the soap service to invoke
	method	The method name of the soap service
	out	the result envelope out parameter like follows

Returns:

H_OK if success

 <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..."
      xmlns:xsi="..."
      xmlns:xsd="...">
    <SOAP-ENV:Body>

     <m:[method] xmlns:m="[urn]">
     </m:[method]>

    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

herror_t soap_env_new_with_response	(	struct SoapEnv *	req,
		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 also:

example csoap/simpleserver.c

Parameters:

	req	The request object. A response object will be created to this request.
	out	the result envelope out paramter like follows

Returns:

H_OK if success

 <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..."
      xmlns:xsi="..."
      xmlns:xsd="...">
    <SOAP-ENV:Body>

     <m:[req-method]Response xmlns:m="[req-urn]">
     </m:[req-method]>

    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

void soap_env_pop_item

(

struct SoapEnv *

env

)

Sets the xml pointer 1 level higher.

Parameters:

env

The envelope object

See also:

soap_env_push_item

xmlNodePtr soap_env_push_item	(	struct SoapEnv *	env,
		const char *	type,
		const char *	name
	)

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.

 <Person type="my:custom">
  <name>Mickey</name>
  <lastname>Mouse</lastname>
 </Person>
 

Returns:

The added xmlNode pointer.

See also:

tutorial