## LmMessageNode

LmMessageNode — A node in the message tree

## Synopsis

                        LmMessageNode;
    const gchar *       lm_message_node_get_value           (LmMessageNode *node);
    void                lm_message_node_set_value           (LmMessageNode *node,
                                                             const gchar *value);
    LmMessageNode *     lm_message_node_add_child           (LmMessageNode *node,
                                                             const gchar *name,
                                                             const gchar *value);
    void                lm_message_node_set_attributes      (LmMessageNode *node,
                                                             const gchar *name,
                                                             ...);
    const gchar *       lm_message_node_get_attribute       (LmMessageNode *node,
                                                             const gchar *name);
    void                lm_message_node_set_attribute       (LmMessageNode *node,
                                                             const gchar *name,
                                                             const gchar *value);
    LmMessageNode *     lm_message_node_get_child           (LmMessageNode *node,
                                                             const gchar *child_name);
    LmMessageNode *     lm_message_node_find_child          (LmMessageNode *node,
                                                             const gchar *child_name);
    gboolean            lm_message_node_get_raw_mode        (LmMessageNode *node);
    void                lm_message_node_set_raw_mode        (LmMessageNode *node,
                                                             gboolean raw_mode);
    LmMessageNode *     lm_message_node_ref                 (LmMessageNode *node);
    void                lm_message_node_unref               (LmMessageNode *node);
    gchar *             lm_message_node_to_string           (LmMessageNode *node);

## Description

Represents a node in the LmMessage tree. These map to XML nodes in the XMPP protocol.

## Details

### LmMessageNode

    typedef struct {
    	gchar      *name;
    	gchar      *value;
    	gboolean    raw_mode;

            LmMessageNode     *next;
            LmMessageNode     *prev;
    	LmMessageNode     *parent;
            LmMessageNode     *children;
    } LmMessageNode;

A struct representing a node in a message.

gchar *`name`; | the name of the node
gchar *`value`; | value of the node, can be NULL
gboolean `raw_mode`; | if true, don't escape the content of the message. The content must be valid XML.
LmMessageNode *`next`; | next sibling
LmMessageNode *`prev`; | previous sibling
LmMessageNode *`parent`; | node parent
LmMessageNode *`children`; | pointing to first child

### lm_message_node_get_value ()

    const gchar *       lm_message_node_get_value           (LmMessageNode *node);

Retrieves the value of `node`.

`node` : | an LmMessageNode
Returns : | The value of the node or `NULL`.

### lm_message_node_set_value ()

    void                lm_message_node_set_value           (LmMessageNode *node,
                                                             const gchar *value);

Sets the value of `node`. If a previous value is set it will be freed.

`node` : | an LmMessageNode
`value` : | the new value.

### lm_message_node_add_child ()

    LmMessageNode *     lm_message_node_add_child           (LmMessageNode *node,
                                                             const gchar *name,
                                                             const gchar *value);

Add a child node with `name` and value set to `value`.

`node` : | an LmMessageNode
`name` : | the name of the new child
`value` : | value of the new child
Returns : | the newly created child

### lm_message_node_set_attributes ()

    void                lm_message_node_set_attributes      (LmMessageNode *node,
                                                             const gchar *name,
                                                             ...);

Sets a list of attributes. The arguments should be names and corresponding value and needs to be ended with `NULL`.

`node` : | an LmMessageNode
`name` : | the first attribute, should be followed by a string with the value
`...` : | The rest of the name/value pairs

### lm_message_node_get_attribute ()

    const gchar *       lm_message_node_get_attribute       (LmMessageNode *node,
                                                             const gchar *name);

Fetches the attribute `name` from `node`.

`node` : | an LmMessageNode
`name` : | the attribute name
Returns : | the attribute value or `NULL` if not set

### lm_message_node_set_attribute ()

    void                lm_message_node_set_attribute       (LmMessageNode *node,
                                                             const gchar *name,
                                                             const gchar *value);

Sets the attribute `name` to `value`.

`node` : | an LmMessageNode
`name` : | name of attribute
`value` : | value of attribute.

### lm_message_node_get_child ()

    LmMessageNode *     lm_message_node_get_child           (LmMessageNode *node,
                                                             const gchar *child_name);

Fetches the child `child_name` from `node`. If child is not found as an immediate child of `node` `NULL` is returned.

`node` : | an LmMessageNode
`child_name` : | the childs name
Returns : | the child node or `NULL` if not found

### lm_message_node_find_child ()

    LmMessageNode *     lm_message_node_find_child          (LmMessageNode *node,
                                                             const gchar *child_name);

Locates a child among all children of `node`. The entire tree will be search until a child with name `child_name` is located.

`node` : | A LmMessageNode
`child_name` : | The name of the child to find
Returns : | the located child or `NULL` if not found

### lm_message_node_get_raw_mode ()

    gboolean            lm_message_node_get_raw_mode        (LmMessageNode *node);

Checks if the nodes value should be sent as raw mode.

`node` : | an LmMessageNode
Returns : | `TRUE` if nodes value should be sent as is and `FALSE` if the value will be escaped before sending.

### lm_message_node_set_raw_mode ()

    void                lm_message_node_set_raw_mode        (LmMessageNode *node,
                                                             gboolean raw_mode);

Set `raw_mode` to `TRUE` if you don't want to escape the value. You need to make sure the value is valid XML yourself.

`node` : | an LmMessageNode
`raw_mode` : | boolean specifying if node value should be escaped or not.

### lm_message_node_ref ()

    LmMessageNode *     lm_message_node_ref                 (LmMessageNode *node);

Adds a reference to `node`.

`node` : | an LmMessageNode
Returns : | the node

### lm_message_node_unref ()

    void                lm_message_node_unref               (LmMessageNode *node);

Removes a reference from `node`. When no more references are present the node is freed. When freed `lm_message_node_unref()` will be called on all children. If caller needs to keep references to the children a call to `lm_message_node_ref()` needs to be done before the call to `lm_message_unref()`.

`node` : | an LmMessageNode

### lm_message_node_to_string ()

    gchar *             lm_message_node_to_string           (LmMessageNode *node);

Returns an XML string representing the node. This is what is sent over the wire. This is used internally Loudmouth and is external for debugging purposes.

`node` : | an LmMessageNode
Returns : | an XML string representation of `node`