## SoupSoapMessage

SoupSoapMessage — A SOAP request

## Synopsis

                        SoupSoapMessage;
    SoupSoapMessage*    soup_soap_message_new               (const char *method,
                                                             const char *uri_string,
                                                             gboolean standalone,
                                                             const char *xml_encoding,
                                                             const char *env_prefix,
                                                             const char *env_uri);
    SoupSoapMessage*    soup_soap_message_new_from_uri      (const char *method,
                                                             const SoupUri *uri,
                                                             gboolean standalone,
                                                             const char *xml_encoding,
                                                             const char *env_prefix,
                                                             const char *env_uri);
    void                soup_soap_message_start_envelope    (SoupSoapMessage *msg);
    void                soup_soap_message_end_envelope      (SoupSoapMessage *msg);
    void                soup_soap_message_start_body        (SoupSoapMessage *msg);
    void                soup_soap_message_end_body          (SoupSoapMessage *msg);
    void                soup_soap_message_start_element     (SoupSoapMessage *msg,
                                                             const char *name,
                                                             const char *prefix,
                                                             const char *ns_uri);
    void                soup_soap_message_end_element       (SoupSoapMessage *msg);
    void                soup_soap_message_start_fault       (SoupSoapMessage *msg,
                                                             const char *faultcode,
                                                             const char *faultstring,
                                                             const char *faultfactor);
    void                soup_soap_message_end_fault         (SoupSoapMessage *msg);
    void                soup_soap_message_start_fault_detail
                                                            (SoupSoapMessage *msg);
    void                soup_soap_message_end_fault_detail  (SoupSoapMessage *msg);
    void                soup_soap_message_start_header      (SoupSoapMessage *msg);
    void                soup_soap_message_end_header        (SoupSoapMessage *msg);
    void                soup_soap_message_start_header_element
                                                            (SoupSoapMessage *msg,
                                                             const char *name,
                                                             gboolean must_understand,
                                                             const char *actor_uri,
                                                             const char *prefix,
                                                             const char *ns_uri);
    void                soup_soap_message_end_header_element
                                                            (SoupSoapMessage *msg);
    void                soup_soap_message_write_int         (SoupSoapMessage *msg,
                                                             glong i);
    void                soup_soap_message_write_double      (SoupSoapMessage *msg,
                                                             double d);
    void                soup_soap_message_write_base64      (SoupSoapMessage *msg,
                                                             const char *string,
                                                             int len);
    void                soup_soap_message_write_time        (SoupSoapMessage *msg,
                                                             const time_t *timeval);
    void                soup_soap_message_write_string      (SoupSoapMessage *msg,
                                                             const char *string);
    void                soup_soap_message_write_buffer      (SoupSoapMessage *msg,
                                                             const char *buffer,
                                                             int len);
    void                soup_soap_message_set_element_type  (SoupSoapMessage *msg,
                                                             const char *xsi_type);
    void                soup_soap_message_set_null          (SoupSoapMessage *msg);
    void                soup_soap_message_add_attribute     (SoupSoapMessage *msg,
                                                             const char *name,
                                                             const char *value,
                                                             const char *prefix,
                                                             const char *ns_uri);
    void                soup_soap_message_add_namespace     (SoupSoapMessage *msg,
                                                             const char *prefix,
                                                             const char *ns_uri);
    void                soup_soap_message_set_default_namespace
                                                            (SoupSoapMessage *msg,
                                                             const char *ns_uri);
    void                soup_soap_message_set_encoding_style
                                                            (SoupSoapMessage *msg,
                                                             const char *enc_style);
    void                soup_soap_message_reset             (SoupSoapMessage *msg);
    void                soup_soap_message_persist           (SoupSoapMessage *msg);
    const char*         soup_soap_message_get_namespace_prefix
                                                            (SoupSoapMessage *msg,
                                                             const char *ns_uri);
    xmlDocPtr           soup_soap_message_get_xml_doc       (SoupSoapMessage *msg);
    SoupSoapResponse*   soup_soap_message_parse_response    (SoupSoapMessage *msg);

## Object Hierarchy

      GObject
       +----SoupMessage
             +----SoupSoapMessage

## Description

## Details

### SoupSoapMessage

    typedef struct _SoupSoapMessage SoupSoapMessage;

### soup_soap_message_new ()

    SoupSoapMessage*    soup_soap_message_new               (const char *method,
                                                             const char *uri_string,
                                                             gboolean standalone,
                                                             const char *xml_encoding,
                                                             const char *env_prefix,
                                                             const char *env_uri);

Creates a new empty SoupSoapMessage, 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 SoupSoapMessage (or `NULL` if `uri_string` could not be parsed).

### soup_soap_message_new_from_uri ()

    SoupSoapMessage*    soup_soap_message_new_from_uri      (const char *method,
                                                             const SoupUri *uri,
                                                             gboolean standalone,
                                                             const char *xml_encoding,
                                                             const char *env_prefix,
                                                             const char *env_uri);

Creates a new empty SoupSoapMessage, 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 SoupSoapMessage

### soup_soap_message_start_envelope ()

    void                soup_soap_message_start_envelope    (SoupSoapMessage *msg);

Starts the top level SOAP Envelope element.

`msg` : | the `SoupSoapMessage`.

### soup_soap_message_end_envelope ()

    void                soup_soap_message_end_envelope      (SoupSoapMessage *msg);

Closes the top level SOAP Envelope element.

`msg` : | the `SoupSoapMessage`.

### soup_soap_message_start_body ()

    void                soup_soap_message_start_body        (SoupSoapMessage *msg);

Starts the SOAP Body element.

`msg` : | the `SoupSoapMessage`.

### soup_soap_message_end_body ()

    void                soup_soap_message_end_body          (SoupSoapMessage *msg);

Closes the SOAP Body element.

`msg` : | the `SoupSoapMessage`.

### soup_soap_message_start_element ()

    void                soup_soap_message_start_element     (SoupSoapMessage *msg,
                                                             const char *name,
                                                             const char *prefix,
                                                             const char *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 SoupSoapMessage.
`name` : | the element name.
`prefix` : | the namespace prefix
`ns_uri` : | the namespace URI

### soup_soap_message_end_element ()

    void                soup_soap_message_end_element       (SoupSoapMessage *msg);

Closes the current message element.

`msg` : | the SoupSoapMessage.

### soup_soap_message_start_fault ()

    void                soup_soap_message_start_fault       (SoupSoapMessage *msg,
                                                             const char *faultcode,
                                                             const char *faultstring,
                                                             const char *faultfactor);

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

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

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

### soup_soap_message_end_fault ()

    void                soup_soap_message_end_fault         (SoupSoapMessage *msg);

Closes the current SOAP Fault element.

`msg` : | the SoupSoapMessage.

### soup_soap_message_start_fault_detail ()

    void                soup_soap_message_start_fault_detail
                                                            (SoupSoapMessage *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 SoupSoapMessage.

### soup_soap_message_end_fault_detail ()

    void                soup_soap_message_end_fault_detail  (SoupSoapMessage *msg);

Closes the current SOAP faultdetail element.

`msg` : | the SoupSoapMessage.

### soup_soap_message_start_header ()

    void                soup_soap_message_start_header      (SoupSoapMessage *msg);

Creates a new SOAP Header element. You can call `soup_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 `soup_soap_message_start_envelope()` and before `soup_soap_message_start_body()`.

`msg` : | the SoupSoapMessage.

### soup_soap_message_end_header ()

    void                soup_soap_message_end_header        (SoupSoapMessage *msg);

Closes the current SOAP Header element.

`msg` : | the SoupSoapMessage.

### soup_soap_message_start_header_element ()

    void                soup_soap_message_start_header_element
                                                            (SoupSoapMessage *msg,
                                                             const char *name,
                                                             gboolean must_understand,
                                                             const char *actor_uri,
                                                             const char *prefix,
                                                             const char *ns_uri);

Starts a new SOAP arbitrary header element.

`msg` : | the SoupSoapMessage.
`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

### soup_soap_message_end_header_element ()

    void                soup_soap_message_end_header_element
                                                            (SoupSoapMessage *msg);

Closes the current SOAP header element.

`msg` : | the SoupSoapMessage.

### soup_soap_message_write_int ()

    void                soup_soap_message_write_int         (SoupSoapMessage *msg,
                                                             glong i);

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

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

### soup_soap_message_write_double ()

    void                soup_soap_message_write_double      (SoupSoapMessage *msg,
                                                             double d);

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

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

### soup_soap_message_write_base64 ()

    void                soup_soap_message_write_base64      (SoupSoapMessage *msg,
                                                             const char *string,
                                                             int len);

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

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

### soup_soap_message_write_time ()

    void                soup_soap_message_write_time        (SoupSoapMessage *msg,
                                                             const time_t *timeval);

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

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

### soup_soap_message_write_string ()

    void                soup_soap_message_write_string      (SoupSoapMessage *msg,
                                                             const char *string);

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

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

### soup_soap_message_write_buffer ()

    void                soup_soap_message_write_buffer      (SoupSoapMessage *msg,
                                                             const char *buffer,
                                                             int len);

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

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

### soup_soap_message_set_element_type ()

    void                soup_soap_message_set_element_type  (SoupSoapMessage *msg,
                                                             const char *xsi_type);

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

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

### soup_soap_message_set_null ()

    void                soup_soap_message_set_null          (SoupSoapMessage *msg);

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

`msg` : | the SoupSoapMessage.

### soup_soap_message_add_attribute ()

    void                soup_soap_message_add_attribute     (SoupSoapMessage *msg,
                                                             const char *name,
                                                             const char *value,
                                                             const char *prefix,
                                                             const char *ns_uri);

Adds an XML attribute to the current element.

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

### soup_soap_message_add_namespace ()

    void                soup_soap_message_add_namespace     (SoupSoapMessage *msg,
                                                             const char *prefix,
                                                             const char *ns_uri);

Adds a new XML namespace to the current element.

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

### soup_soap_message_set_default_namespace ()

    void                soup_soap_message_set_default_namespace
                                                            (SoupSoapMessage *msg,
                                                             const char *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 SoupSoapMessage.
`ns_uri` : | the namespace URI.

### soup_soap_message_set_encoding_style ()

    void                soup_soap_message_set_encoding_style
                                                            (SoupSoapMessage *msg,
                                                             const char *enc_style);

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

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

### soup_soap_message_reset ()

    void                soup_soap_message_reset             (SoupSoapMessage *msg);

Resets the internal XML representation of the SOAP message.

`msg` : | the SoupSoapMessage.

### soup_soap_message_persist ()

    void                soup_soap_message_persist           (SoupSoapMessage *msg);

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

`msg` : | the SoupSoapMessage.

### soup_soap_message_get_namespace_prefix ()

    const char*         soup_soap_message_get_namespace_prefix
                                                            (SoupSoapMessage *msg,
                                                             const char *ns_uri);

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

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

### soup_soap_message_get_xml_doc ()

    xmlDocPtr           soup_soap_message_get_xml_doc       (SoupSoapMessage *msg);

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

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

### soup_soap_message_parse_response ()

    SoupSoapResponse*   soup_soap_message_parse_response    (SoupSoapMessage *msg);

Parses the response returned by the server.

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