LmMessage

## LmMessage LmMessage — A message is built up like a tree of message nodes. |

## Synopsis

                        LmMessage;
    enum                LmMessageType;
    enum                LmMessageSubType;
    LmMessage *         lm_message_new                      (const gchar *to,
                                                             LmMessageType type);
    LmMessage *         lm_message_new_with_sub_type        (const gchar *to,
                                                             LmMessageType type,
                                                             LmMessageSubType sub_type);
    LmMessageType       lm_message_get_type                 (LmMessage *message);
    LmMessageSubType    lm_message_get_sub_type             (LmMessage *message);
    LmMessageNode *     lm_message_get_node                 (LmMessage *message);
    LmMessage *         lm_message_ref                      (LmMessage *message);
    void                lm_message_unref                    (LmMessage *message);

## Description

Represents a message that can be sent with `lm_connection_send()`, `lm_connection_send_with_reply()` or `lm_connection_send_with_reply_and_block()`. Either use `lm_message_new()` or `lm_message_new_with_subtype()` to create a message. You need to call `lm_message_unref()` when are finished with it.

## Details

### LmMessage

    typedef struct {
    	LmMessageNode *node;

    	LmMessagePriv *priv;
    } LmMessage;

The LmMessage struct

LmMessageNode *`node`; | The root node of the message, you can also use `lm_message_get_node()` to retrieve this.
LmMessagePriv *`priv`; | A pointer to message private data. Should never be touched from application code.

### enum LmMessageType

    typedef enum {
    	LM_MESSAGE_TYPE_MESSAGE,
    	LM_MESSAGE_TYPE_PRESENCE,
    	LM_MESSAGE_TYPE_IQ,
    	LM_MESSAGE_TYPE_STREAM,
    	LM_MESSAGE_TYPE_STREAM_ERROR,
    	LM_MESSAGE_TYPE_STREAM_FEATURES,
    	LM_MESSAGE_TYPE_AUTH,
    	LM_MESSAGE_TYPE_CHALLENGE,
    	LM_MESSAGE_TYPE_RESPONSE,
    	LM_MESSAGE_TYPE_SUCCESS,
    	LM_MESSAGE_TYPE_FAILURE,
    	LM_MESSAGE_TYPE_PROCEED,
    	LM_MESSAGE_TYPE_STARTTLS,
    	LM_MESSAGE_TYPE_UNKNOWN
    } LmMessageType;

Describes what type of message a message is. This maps directly to top level elements in the jabber protocol.

`LM_MESSAGE_TYPE_MESSAGE` | a message, <message></message>
`LM_MESSAGE_TYPE_PRESENCE` | a presence element, <presence></presence>
`LM_MESSAGE_TYPE_IQ` | an info/query element, <iq></iq>
`LM_MESSAGE_TYPE_STREAM` | the stream:stream element, you probably don't need to create a message of this type.
`LM_MESSAGE_TYPE_STREAM_ERROR` | a stream:error element
`LM_MESSAGE_TYPE_STREAM_FEATURES` | Internal
`LM_MESSAGE_TYPE_AUTH` | Internal
`LM_MESSAGE_TYPE_CHALLENGE` | Internal
`LM_MESSAGE_TYPE_RESPONSE` | Internal
`LM_MESSAGE_TYPE_SUCCESS` | Internal
`LM_MESSAGE_TYPE_FAILURE` | Internal
`LM_MESSAGE_TYPE_PROCEED` | Internal
`LM_MESSAGE_TYPE_STARTTLS` | Internal
`LM_MESSAGE_TYPE_UNKNOWN` | incoming message is of some unknown type.

### enum LmMessageSubType

    typedef enum {
            LM_MESSAGE_SUB_TYPE_NOT_SET = -10,
    	LM_MESSAGE_SUB_TYPE_AVAILABLE = -1,
    	LM_MESSAGE_SUB_TYPE_NORMAL = 0,
    	LM_MESSAGE_SUB_TYPE_CHAT,
            LM_MESSAGE_SUB_TYPE_GROUPCHAT,
            LM_MESSAGE_SUB_TYPE_HEADLINE,
            LM_MESSAGE_SUB_TYPE_UNAVAILABLE,
            LM_MESSAGE_SUB_TYPE_PROBE,
            LM_MESSAGE_SUB_TYPE_SUBSCRIBE,
            LM_MESSAGE_SUB_TYPE_UNSUBSCRIBE,
            LM_MESSAGE_SUB_TYPE_SUBSCRIBED,
            LM_MESSAGE_SUB_TYPE_UNSUBSCRIBED,
    	LM_MESSAGE_SUB_TYPE_GET,
    	LM_MESSAGE_SUB_TYPE_SET,
    	LM_MESSAGE_SUB_TYPE_RESULT,
    	LM_MESSAGE_SUB_TYPE_ERROR
    } LmMessageSubType;

Describes the sub type of a message. This is equal to the "type" attribute in the jabber protocol. What sub type a message can have is depending on the type of the message.

`LM_MESSAGE_SUB_TYPE_NOT_SET` | the default. No "type" attribute will be sent.
`LM_MESSAGE_SUB_TYPE_AVAILABLE` | presence is available, applies to message type "presence"
`LM_MESSAGE_SUB_TYPE_NORMAL` | a normal message.
`LM_MESSAGE_SUB_TYPE_CHAT` | message is a chat message, applies to message type "message"
`LM_MESSAGE_SUB_TYPE_GROUPCHAT` | message is a group chat message, applies to message type "message"
`LM_MESSAGE_SUB_TYPE_HEADLINE` | message is a headline message, applies to message type "message"
`LM_MESSAGE_SUB_TYPE_UNAVAILABLE` | presence is unavailable, applies to message type "presence"
`LM_MESSAGE_SUB_TYPE_PROBE` | a probe presence, applies to message type "presence"
`LM_MESSAGE_SUB_TYPE_SUBSCRIBE` | try to subscribe to another jids presence, applies to message type "presence"
`LM_MESSAGE_SUB_TYPE_UNSUBSCRIBE` | unsubscribes from another jids presence, applies to message type "presence"
`LM_MESSAGE_SUB_TYPE_SUBSCRIBED` | reply from a subscribe message, informs that the subscription was successful. Applies to message type "presence"
`LM_MESSAGE_SUB_TYPE_UNSUBSCRIBED` | reply from subscribe or unsubscribe message. If it's a reply from a subscribe message it notifies that the subscription failed. Applies to message type "presence"
`LM_MESSAGE_SUB_TYPE_GET` | used to get information from an IQ query, applies to message type "iq"
`LM_MESSAGE_SUB_TYPE_SET` | used to set information in a IQ call, applised to message type "iq"
`LM_MESSAGE_SUB_TYPE_RESULT` | message is an IQ reply, applies to message type "iq"
`LM_MESSAGE_SUB_TYPE_ERROR` | messages is an error, applies to all message types.

### lm_message_new ()

    LmMessage *         lm_message_new                      (const gchar *to,
                                                             LmMessageType type);

Creates a new LmMessage which can be sent with `lm_connection_send()` or `lm_connection_send_with_reply()`. If `to` is `NULL` the message is sent to the server. The returned message should be unreferenced with `lm_message_unref()` when caller is finished with it.

`to` : | receipient jid
`type` : | message type
Returns : | a newly created LmMessage

### lm_message_new_with_sub_type ()

    LmMessage *         lm_message_new_with_sub_type        (const gchar *to,
                                                             LmMessageType type,
                                                             LmMessageSubType sub_type);

Creates a new LmMessage with sub type set. See `lm_message_new()` for more information.

`to` : | receipient jid
`type` : | message type
`sub_type` : | message sub type
Returns : | a newly created LmMessage

### lm_message_get_type ()

    LmMessageType       lm_message_get_type                 (LmMessage *message);

Fetches the type of `message`.

`message` : | an LmMessage
Returns : | the message type

### lm_message_get_sub_type ()

    LmMessageSubType    lm_message_get_sub_type             (LmMessage *message);

Fetches the sub type of `message`.

`message` : | an LmMessage
Returns : | the message sub type

### lm_message_get_node ()

    LmMessageNode *     lm_message_get_node                 (LmMessage *message);

Retrieves the root node from `message`.

`message` : | an LmMessage
Returns : | an LmMessageNode

### lm_message_ref ()

    LmMessage *         lm_message_ref                      (LmMessage *message);

Adds a reference to `message`.

`message` : | an LmMessage
Returns : | the message

### lm_message_unref ()

    void                lm_message_unref                    (LmMessage *message);

Removes a reference from `message`. When no more references are present the message is freed.

`message` : | an LmMessage