Loudmouth Reference Manual: LmMessage

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

## Functions

LmMessage * | lm_message_new ()
LmMessage * | lm_message_new_with_sub_type ()
LmMessageType | lm_message_get_type ()
LmMessageSubType | lm_message_get_sub_type ()
LmMessageNode * | lm_message_get_node ()
LmMessage * | lm_message_ref ()
void | lm_message_unref ()

## Types and Values

| LmMessage
enum | LmMessageType
enum | LmMessageSubType

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

## Functions

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Returns

the message sub type

### lm_message_get_node ()

    LmMessageNode *
    lm_message_get_node (LmMessage *message);

Retrieves the root node from `message` .

#### Parameters

message | an LmMessage |

#### Returns

an LmMessageNode

### lm_message_ref ()

    LmMessage *
    lm_message_ref (LmMessage *message);

Adds a reference to `message` .

#### Parameters

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.

#### Parameters

message | an LmMessage |

## Types and Values

### LmMessage

    typedef struct {
        LmMessageNode *node;

        LmMessagePriv *priv;
    } LmMessage;

### enum LmMessageType

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

#### Members

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 |  |
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 | incoming message is of some unknown type. |

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

#### Members

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