## ESoapMessage

ESoapMessage

## Synopsis

                        ESoapMessage;
    ESoapMessage *      e_soap_message_new                  (const gchar *method,
                                                             const gchar *uri_string,
                                                             gboolean standalone,
                                                             const gchar *xml_encoding,
                                                             const gchar *env_prefix,
                                                             const gchar *env_uri);
    ESoapMessage *      e_soap_message_new_from_uri         (const gchar *method,
                                                             SoupURI *uri,
                                                             gboolean standalone,
                                                             const gchar *xml_encoding,
                                                             const gchar *env_prefix,
                                                             const gchar *env_uri);
    void                e_soap_message_start_envelope       (ESoapMessage *msg);
    void                e_soap_message_end_envelope         (ESoapMessage *msg);
    void                e_soap_message_start_body           (ESoapMessage *msg);
    void                e_soap_message_end_body             (ESoapMessage *msg);
    void                e_soap_message_start_element        (ESoapMessage *msg,
                                                             const gchar *name,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);
    void                e_soap_message_end_element          (ESoapMessage *msg);
    void                e_soap_message_start_fault          (ESoapMessage *msg,
                                                             const gchar *faultcode,
                                                             const gchar *faultstring,
                                                             const gchar *faultfactor);
    void                e_soap_message_end_fault            (ESoapMessage *msg);
    void                e_soap_message_start_fault_detail   (ESoapMessage *msg);
    void                e_soap_message_end_fault_detail     (ESoapMessage *msg);
    void                e_soap_message_start_header         (ESoapMessage *msg);
    void                e_soap_message_end_header           (ESoapMessage *msg);
    void                e_soap_message_start_header_element (ESoapMessage *msg,
                                                             const gchar *name,
                                                             gboolean must_understand,
                                                             const gchar *actor_uri,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);
    void                e_soap_message_end_header_element   (ESoapMessage *msg);
    void                e_soap_message_write_int            (ESoapMessage *msg,
                                                             glong i);
    void                e_soap_message_write_double         (ESoapMessage *msg,
                                                             gdouble d);
    void                e_soap_message_write_base64         (ESoapMessage *msg,
                                                             const gchar *string,
                                                             gint len);
    void                e_soap_message_write_time           (ESoapMessage *msg,
                                                             const time_t *timeval);
    void                e_soap_message_write_string         (ESoapMessage *msg,
                                                             const gchar *string);
    void                e_soap_message_write_buffer         (ESoapMessage *msg,
                                                             const gchar *buffer,
                                                             gint len);
    void                e_soap_message_set_element_type     (ESoapMessage *msg,
                                                             const gchar *xsi_type);
    void                e_soap_message_set_null             (ESoapMessage *msg);
    void                e_soap_message_add_attribute        (ESoapMessage *msg,
                                                             const gchar *name,
                                                             const gchar *value,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);
    void                e_soap_message_add_namespace        (ESoapMessage *msg,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);
    void                e_soap_message_set_default_namespace
                                                            (ESoapMessage *msg,
                                                             const gchar *ns_uri);
    void                e_soap_message_set_encoding_style   (ESoapMessage *msg,
                                                             const gchar *enc_style);
    void                e_soap_message_reset                (ESoapMessage *msg);
    void                e_soap_message_persist              (ESoapMessage *msg);
    const gchar *       e_soap_message_get_namespace_prefix (ESoapMessage *msg,
                                                             const gchar *ns_uri);
    xmlDocPtr           e_soap_message_get_xml_doc          (ESoapMessage *msg);
    ESoapResponse *     e_soap_message_parse_response       (ESoapMessage *msg);

## Description

## Details

### ESoapMessage

    typedef struct {
    	SoupMessage parent;

    	ESoapMessagePrivate *priv;
    } ESoapMessage;

### e_soap_message_new ()

    ESoapMessage *      e_soap_message_new                  (const gchar *method,
                                                             const gchar *uri_string,
                                                             gboolean standalone,
                                                             const gchar *xml_encoding,
                                                             const gchar *env_prefix,
                                                             const gchar *env_uri);

Creates a new empty ESoapMessage, which will connect to `uri_string`.

`method` : | the HTTP method for the created request.
`uri_string` : | the destination endpoint (as a string).
`standalone` : | ??? FIXME
`xml_encoding` : | ??? FIXME
`env_prefix` : | ??? FIXME
`env_uri` : | ??? FIXME
Returns : | the new ESoapMessage (or `NULL` if `uri_string` could not be parsed).

Since 3.0

### e_soap_message_new_from_uri ()

    ESoapMessage *      e_soap_message_new_from_uri         (const gchar *method,
                                                             SoupURI *uri,
                                                             gboolean standalone,
                                                             const gchar *xml_encoding,
                                                             const gchar *env_prefix,
                                                             const gchar *env_uri);

Creates a new empty ESoapMessage, which will connect to `uri`

`method` : | the HTTP method for the created request.
`uri` : | the destination endpoint (as a SoupURI).
`standalone` : | ??? FIXME
`xml_encoding` : | ??? FIXME
`env_prefix` : | ??? FIXME
`env_uri` : | ??? FIXME
Returns : | the new ESoapMessage

Since 3.0

### e_soap_message_start_envelope ()

    void                e_soap_message_start_envelope       (ESoapMessage *msg);

Starts the top level SOAP Envelope element.

`msg` : | the `ESoapMessage`.

Since 3.0

### e_soap_message_end_envelope ()

    void                e_soap_message_end_envelope         (ESoapMessage *msg);

Closes the top level SOAP Envelope element.

`msg` : | the `ESoapMessage`.

Since 3.0

### e_soap_message_start_body ()

    void                e_soap_message_start_body           (ESoapMessage *msg);

Starts the SOAP Body element.

`msg` : | the `ESoapMessage`.

Since 3.0

### e_soap_message_end_body ()

    void                e_soap_message_end_body             (ESoapMessage *msg);

Closes the SOAP Body element.

`msg` : | the `ESoapMessage`.

Since 3.0

### e_soap_message_start_element ()

    void                e_soap_message_start_element        (ESoapMessage *msg,
                                                             const gchar *name,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);

Starts a new arbitrary message element, with `name` as the element name, `prefix` as the XML Namespace prefix, and `ns_uri` as the XML Namespace uri for * the created element.

Passing `prefix` with no `ns_uri` will cause a recursive search for an existing namespace with the same prefix. Failing that a new ns will be created with an empty uri.

Passing both `prefix` and `ns_uri` always causes new namespace attribute creation.

Passing NULL for both `prefix` and `ns_uri` causes no prefix to be used, and the element will be in the default namespace.

`msg` : | the ESoapMessage.
`name` : | the element name.
`prefix` : | the namespace prefix
`ns_uri` : | the namespace URI

Since 3.0

### e_soap_message_end_element ()

    void                e_soap_message_end_element          (ESoapMessage *msg);

Closes the current message element.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_start_fault ()

    void                e_soap_message_start_fault          (ESoapMessage *msg,
                                                             const gchar *faultcode,
                                                             const gchar *faultstring,
                                                             const gchar *faultfactor);

Starts a new SOAP Fault element, creating faultcode, faultstring, and faultfactor child elements.

If you wish to add the faultdetail element, use `e_soap_message_start_fault_detail()`, and then `e_soap_message_start_element()` to add arbitrary sub-elements.

`msg` : | the ESoapMessage.
`faultcode` : | faultcode element value
`faultstring` : | faultstring element value
`faultfactor` : | faultfactor element value

Since 3.0

### e_soap_message_end_fault ()

    void                e_soap_message_end_fault            (ESoapMessage *msg);

Closes the current SOAP Fault element.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_start_fault_detail ()

    void                e_soap_message_start_fault_detail   (ESoapMessage *msg);

Start the faultdetail child element of the current SOAP Fault element. The faultdetail element allows arbitrary data to be sent in a returned fault.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_end_fault_detail ()

    void                e_soap_message_end_fault_detail     (ESoapMessage *msg);

Closes the current SOAP faultdetail element.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_start_header ()

    void                e_soap_message_start_header         (ESoapMessage *msg);

Creates a new SOAP Header element. You can call `e_soap_message_start_header_element()` after this to add a new header child element. SOAP Header elements allow out-of-band data to be transferred while not interfering with the message body.

This should be called after `e_soap_message_start_envelope()` and before `e_soap_message_start_body()`.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_end_header ()

    void                e_soap_message_end_header           (ESoapMessage *msg);

Closes the current SOAP Header element.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_start_header_element ()

    void                e_soap_message_start_header_element (ESoapMessage *msg,
                                                             const gchar *name,
                                                             gboolean must_understand,
                                                             const gchar *actor_uri,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);

Starts a new SOAP arbitrary header element.

`msg` : | the ESoapMessage.
`name` : | name of the header element
`must_understand` : | whether the recipient must understand the header in order to proceed with processing the message
`actor_uri` : | the URI which represents the destination actor for this header.
`prefix` : | the namespace prefix
`ns_uri` : | the namespace URI

Since 3.0

### e_soap_message_end_header_element ()

    void                e_soap_message_end_header_element   (ESoapMessage *msg);

Closes the current SOAP header element.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_write_int ()

    void                e_soap_message_write_int            (ESoapMessage *msg,
                                                             glong i);

Writes the stringified value of `i` as the current element's content.

`msg` : | the ESoapMessage.
`i` : | the integer value to write.

Since 3.0

### e_soap_message_write_double ()

    void                e_soap_message_write_double         (ESoapMessage *msg,
                                                             gdouble d);

Writes the stringified value of `d` as the current element's content.

`msg` : | the ESoapMessage.
`d` : | the double value to write.

Since 3.0

### e_soap_message_write_base64 ()

    void                e_soap_message_write_base64         (ESoapMessage *msg,
                                                             const gchar *string,
                                                             gint len);

Writes the Base-64 encoded value of `string` as the current element's content.

`msg` : | the ESoapMessage
`string` : | the binary data buffer to encode
`len` : | the length of data to encode

Since 3.0

### e_soap_message_write_time ()

    void                e_soap_message_write_time           (ESoapMessage *msg,
                                                             const time_t *timeval);

Writes the stringified value of `timeval` as the current element's content.

`msg` : | the ESoapMessage.
`timeval` : | pointer to a time_t to encode

Since 3.0

### e_soap_message_write_string ()

    void                e_soap_message_write_string         (ESoapMessage *msg,
                                                             const gchar *string);

Writes the `string` as the current element's content.

`msg` : | the ESoapMessage.
`string` : | string to write.

Since 3.0

### e_soap_message_write_buffer ()

    void                e_soap_message_write_buffer         (ESoapMessage *msg,
                                                             const gchar *buffer,
                                                             gint len);

Writes the string buffer pointed to by `buffer` as the current element's content.

`msg` : | the ESoapMessage.
`buffer` : | the string data buffer to write.
`len` : | length of `buffer`.

Since 3.0

### e_soap_message_set_element_type ()

    void                e_soap_message_set_element_type     (ESoapMessage *msg,
                                                             const gchar *xsi_type);

Sets the current element's XML schema xsi:type attribute, which specifies the element's type name.

`msg` : | the ESoapMessage.
`xsi_type` : | the type name for the element.

Since 3.0

### e_soap_message_set_null ()

    void                e_soap_message_set_null             (ESoapMessage *msg);

Sets the current element's XML Schema xsi:null attribute.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_add_attribute ()

    void                e_soap_message_add_attribute        (ESoapMessage *msg,
                                                             const gchar *name,
                                                             const gchar *value,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);

Adds an XML attribute to the current element.

`msg` : | the ESoapMessage.
`name` : | name of the attribute
`value` : | value of the attribute
`prefix` : | the namespace prefix
`ns_uri` : | the namespace URI

Since 3.0

### e_soap_message_add_namespace ()

    void                e_soap_message_add_namespace        (ESoapMessage *msg,
                                                             const gchar *prefix,
                                                             const gchar *ns_uri);

Adds a new XML namespace to the current element.

`msg` : | the ESoapMessage.
`prefix` : | the namespace prefix
`ns_uri` : | the namespace URI, or NULL for empty namespace

Since 3.0

### e_soap_message_set_default_namespace ()

    void                e_soap_message_set_default_namespace
                                                            (ESoapMessage *msg,
                                                             const gchar *ns_uri);

Sets the default namespace to the URI specified in `ns_uri`. The default namespace becomes the namespace all non-explicitly namespaced child elements fall into.

`msg` : | the ESoapMessage.
`ns_uri` : | the namespace URI.

Since 3.0

### e_soap_message_set_encoding_style ()

    void                e_soap_message_set_encoding_style   (ESoapMessage *msg,
                                                             const gchar *enc_style);

Sets the encodingStyle attribute on the current element to the value of `enc_style`.

`msg` : | the ESoapMessage.
`enc_style` : | the new encodingStyle value

Since 3.0

### e_soap_message_reset ()

    void                e_soap_message_reset                (ESoapMessage *msg);

Resets the internal XML representation of the SOAP message.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_persist ()

    void                e_soap_message_persist              (ESoapMessage *msg);

Writes the serialized XML tree to the SoupMessage's buffer.

`msg` : | the ESoapMessage.

Since 3.0

### e_soap_message_get_namespace_prefix ()

    const gchar *       e_soap_message_get_namespace_prefix (ESoapMessage *msg,
                                                             const gchar *ns_uri);

Returns the namespace prefix for `ns_uri` (or an empty string if `ns_uri` is set to the default namespace)

`msg` : | the ESoapMessage.
`ns_uri` : | the namespace URI.
Returns : | The namespace prefix, or `NULL` if no namespace exists for the URI given.

Since 3.0

### e_soap_message_get_xml_doc ()

    xmlDocPtr           e_soap_message_get_xml_doc          (ESoapMessage *msg);

Returns the internal XML representation tree of the ESoapMessage pointed to by `msg`.

`msg` : | the ESoapMessage.
Returns : | the xmlDocPtr representing the SOAP message.

Since 3.0

### e_soap_message_parse_response ()

    ESoapResponse *     e_soap_message_parse_response       (ESoapMessage *msg);

Parses the response returned by the server.

`msg` : | the ESoapMessage.
Returns : | a ESoapResponse representing the response from the server, or `NULL` if there was an error.

Since 3.0