Loudmouth Reference Manual: LmMessageNode

## LmMessageNode LmMessageNode — A node in the message tree |

## Functions

const gchar * | lm_message_node_get_value ()
void | lm_message_node_set_value ()
LmMessageNode * | lm_message_node_add_child ()
void | lm_message_node_set_attributes ()
const gchar * | lm_message_node_get_attribute ()
void | lm_message_node_set_attribute ()
LmMessageNode * | lm_message_node_get_child ()
LmMessageNode * | lm_message_node_find_child ()
gboolean | lm_message_node_get_raw_mode ()
void | lm_message_node_set_raw_mode ()
LmMessageNode * | lm_message_node_ref ()
void | lm_message_node_unref ()
gchar * | lm_message_node_to_string ()

## Types and Values

struct | LmMessageNode

## Description

## Functions

### lm_message_node_get_value ()

    const gchar *
    lm_message_node_get_value (LmMessageNode *node);

Retrieves the value of `node` .

#### Parameters

node | an LmMessageNode |

#### Returns

### 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.

#### Parameters

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` .

#### Parameters

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`.

#### Parameters

node | an LmMessageNode |
name | the first attribute, should be followed by a string with the value |
Varargs | 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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

node | an LmMessageNode |

#### Returns

an XML string representation of `node`

## Types and Values

### struct LmMessageNode

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

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

A struct representing a node in a message.

#### Members

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 |