## TpCMMessage TpCMMessage — a message in the Telepathy message interface, CM side |

## Synopsis

    #include <telepathy-glib/telepathy-glib.h>

                        TpCMMessage;
    TpMessage *         tp_cm_message_new                   (TpBaseConnection *connection,
                                                             guint initial_parts);
    TpMessage *         tp_cm_message_new_text              (TpBaseConnection *conn,
                                                             TpHandle sender,
                                                             TpChannelTextMessageType type,
                                                             const gchar *text);
    void                tp_cm_message_set_message           (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             TpMessage *message);
    void                tp_cm_message_take_message          (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             TpMessage *message);
    TpHandle            tp_cm_message_get_sender            (TpMessage *self);
    void                tp_cm_message_set_sender            (TpMessage *self,
                                                             TpHandle handle);

## Object Hierarchy

      GObject
       +----TpMessage
             +----TpCMMessage

## Description

TpCMMessage is used within connection managers to represent a message sent or received using the Messages interface.

## Details

### TpCMMessage

    typedef struct _TpCMMessage TpCMMessage;

Opaque structure representing a message in the Telepathy messages interface (an array of at least one mapping from string to variant, where the first mapping contains message headers and subsequent mappings contain the message body).

Since 0.13.9

### tp_cm_message_new ()

    TpMessage *         tp_cm_message_new                   (TpBaseConnection *connection,
                                                             guint initial_parts);

`connection` : | a connection on which to reference handles
`initial_parts` : | number of parts to create (at least 1)
Returns : | a newly allocated message suitable to be passed to `tp_cm_message_mixin_take_received()`

Since 0.13.9

### tp_cm_message_new_text ()

    TpMessage *         tp_cm_message_new_text              (TpBaseConnection *conn,
                                                             TpHandle sender,
                                                             TpChannelTextMessageType type,
                                                             const gchar *text);

A convenient function to create a new TpCMMessage having 'text/plain' as 'content-type', `type` as 'message-type', `text` as 'content' and `sender` as its sender.

`conn` : | a connection
`sender` : | the TpHandle of the sender of the message
`type` : | the type of message
`text` : | content of the messsage
Returns : | a newly allocated TpCMMessage. [transfer full]

Since 0.13.10

### tp_cm_message_set_message ()

    void                tp_cm_message_set_message           (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             TpMessage *message);

Set `key` in part `part` of `self` to have `message` as an aa{sv} value (that is, an array of Message_Part).

`self` : | a message
`part` : | a part number, which must be strictly less than the number returned by `tp_message_count_parts()`
`key` : | a key in the mapping representing the part
`message` : | another (distinct) message created for the same TpBaseConnection

Since 0.15.5

### tp_cm_message_take_message ()

    void                tp_cm_message_take_message          (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             TpMessage *message);

Set `key` in part `part` of `self` to have `message` as an aa{sv} value (that is, an array of Message_Part), and take ownership of `message`. The caller should not use `message` after passing it to this function. All handle references owned by `message` will subsequently belong to and be released with `self`.

`self` : | a message
`part` : | a part number, which must be strictly less than the number returned by `tp_message_count_parts()`
`key` : | a key in the mapping representing the part
`message` : | another (distinct) message created for the same TpBaseConnection

Since 0.13.9

### tp_cm_message_get_sender ()

    TpHandle            tp_cm_message_get_sender            (TpMessage *self);

Return the sender of `self`, i.e. the "message-sender" key of the header, or 0 if there is no sender.

`self` : | a TpCMMessage
Returns : | a `TP_HANDLE_TYPE_CONTACT` handle, or 0

Since 0.13.9

### tp_cm_message_set_sender ()

    void                tp_cm_message_set_sender            (TpMessage *self,
                                                             TpHandle handle);

Set the sender of `self`, i.e. the "message-sender" and "message-sender-id" keys in the header.

`self` : | a TpCMMessage
`handle` : | the TpHandle of the sender of the message

Since 0.13.9