soap-env.h File Reference

Go to the source code of this file.

Classes

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 grammar rules are as follows:

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:

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.

Definition in file soap-env.h.


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)
 

Definition at line 133 of file soap-env.h.


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

Definition at line 363 of file soap-env.c.

References SoapEnv::cur, and log_error1.

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:

Definition at line 389 of file soap-env.c.

References XmlNodeHolder::node, and soap_env_get_method().

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

Definition at line 322 of file soap-env.c.

References SoapEnv::cur, and log_error1.

Referenced by soap_env_add_itemf(), and soap_env_push_item().

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

Definition at line 348 of file soap-env.c.

References soap_env_add_item().

const char* soap_env_find_methodname struct SoapEnv env  ) 
 

Get the method of the message.

Definition at line 626 of file soap-env.c.

References log_error1, XmlNodeHolder::node, soap_env_get_body(), and soap_xml_get_children().

Referenced by soap_env_new_with_response(), and soap_server_process().

const char* soap_env_find_urn struct SoapEnv env  ) 
 

Get the URN of the message.

Definition at line 587 of file soap-env.c.

References log_error1, log_verbose1, log_warn1, XmlNodeHolder::node, soap_env_get_body(), and soap_xml_get_children().

Referenced by soap_env_new_with_response(), and soap_server_process().

void soap_env_free struct SoapEnv env  ) 
 

Free the envelope.

Parameters:
env The envelope object

Definition at line 426 of file soap-env.c.

References SoapEnv::root.

Referenced by soap_ctx_free().

xmlNodePtr soap_env_get_body struct SoapEnv env  ) 
 

Gets the xml node pointing to SOAP Body.

Definition at line 442 of file soap-env.c.

References log_error1, XmlNodeHolder::node, SoapEnv::root, soap_xml_get_children(), and soap_xml_get_next().

Referenced by soap_env_find_methodname(), soap_env_find_urn(), soap_env_get_fault(), soap_env_get_method(), and soap_env_new_from_doc().

xmlNodePtr soap_env_get_fault struct SoapEnv env  ) 
 

Get the xml node pointing to SOAP Fault

Definition at line 499 of file soap-env.c.

References XmlNodeHolder::node, soap_env_get_body(), and soap_xml_get_next().

xmlNodePtr soap_env_get_header struct SoapEnv env  ) 
 

Get the xml node pointing to SOAP Header

Definition at line 471 of file soap-env.c.

References log_error1, XmlNodeHolder::node, SoapEnv::root, soap_xml_get_children(), and soap_xml_get_next().

Referenced by soap_env_new_from_doc().

xmlNodePtr soap_env_get_method struct SoapEnv env  ) 
 

Get the xml node pointing to SOAP method (call)

Definition at line 521 of file soap-env.c.

References log_verbose1, soap_env_get_body(), and soap_xml_get_children().

Referenced by soap_env_add_custom(), soap_env_new_from_doc(), soap_xmlsec_decrypt(), and soap_xmlsec_encrypt().

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

Definition at line 205 of file soap-env.c.

References GENERAL_INVALID_PARAM, H_OK, herror_new(), soap_env_new_from_doc(), and XML_ERROR_PARSE.

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

Definition at line 168 of file soap-env.c.

References SoapEnv::body, SoapEnv::cur, GENERAL_INVALID_PARAM, H_OK, SoapEnv::header, herror_new(), log_error1, log_error2, SoapEnv::root, soap_env_get_body(), soap_env_get_header(), soap_env_get_method(), and XML_ERROR_EMPTY_DOCUMENT.

Referenced by soap_env_new_from_buffer(), soap_env_new_with_fault(), soap_env_new_with_method(), and soap_nudp_server_run().

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

Definition at line 227 of file soap-env.c.

References H_OK, herror_new(), soap_env_new_from_doc(), soap_fault_build(), and XML_ERROR_PARSE.

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>

 

Definition at line 292 of file soap-env.c.

References _SOAP_MSG_TEMPLATE_, _SOAP_MSG_TEMPLATE_EMPTY_TARGET_, herror_new(), log_verbose2, soap_env_new_from_doc(), and XML_ERROR_PARSE.

Referenced by soap_ctx_new_with_method(), and soap_env_new_with_response().

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>

 

Definition at line 243 of file soap-env.c.

References GENERAL_INVALID_PARAM, herror_new(), SoapEnv::root, soap_env_find_methodname(), soap_env_find_urn(), and soap_env_new_with_method().

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

Definition at line 417 of file soap-env.c.

References SoapEnv::cur.

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

Definition at line 404 of file soap-env.c.

References SoapEnv::cur, XmlNodeHolder::node, and soap_env_add_item().


Generated on Thu Jan 25 23:36:04 2007 for csoap by  doxygen 1.4.6