## TpMessage

TpMessage — a message in the Telepathy message interface

## Synopsis

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

                        TpMessage;
    guint               tp_message_count_parts              (TpMessage *self);
    GVariant *          tp_message_dup_part                 (TpMessage *self,
                                                             guint part);
    const GHashTable *  tp_message_peek                     (TpMessage *self,
                                                             guint part);
    gchar *             tp_message_to_text                  (TpMessage *message,
                                                             TpChannelTextMessageFlags *out_flags);
    TpChannelTextMessageType tp_message_get_message_type    (TpMessage *self);
    gint64              tp_message_get_received_timestamp   (TpMessage *self);
    gint64              tp_message_get_sent_timestamp       (TpMessage *self);
    const gchar *       tp_message_get_specific_to_interface
                                                            (TpMessage *self);
    const gchar *       tp_message_get_supersedes           (TpMessage *self);
    const gchar *       tp_message_get_token                (TpMessage *self);
    gboolean            tp_message_is_delivery_report       (TpMessage *self);
    gboolean            tp_message_is_rescued               (TpMessage *self);
    gboolean            tp_message_is_scrollback            (TpMessage *self);
    guint32             tp_message_get_pending_message_id   (TpMessage *self,
                                                             gboolean *valid);

    gboolean            tp_message_is_mutable               (TpMessage *self);
    guint               tp_message_append_part              (TpMessage *self);
    gboolean            tp_message_delete_key               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key);
    void                tp_message_delete_part              (TpMessage *self,
                                                             guint part);
    void                tp_message_set                      (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             const GValue *source);
    void                tp_message_set_variant              (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             GVariant *value);
    void                tp_message_set_boolean              (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             gboolean b);
    void                tp_message_set_bytes                (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             guint len,
                                                             gconstpointer bytes);
    #define             tp_message_set_int16                (s,
                                                             p,
                                                             k,
                                                             i)
    void                tp_message_set_int32                (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             gint32 i);
    void                tp_message_set_int64                (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             gint64 i);
    void                tp_message_set_string               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             const gchar *s);
    void                tp_message_set_string_printf        (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             const gchar *fmt,
                                                             ...);
    #define             tp_message_set_uint16               (s,
                                                             p,
                                                             k,
                                                             u)
    void                tp_message_set_uint32               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             guint32 u);
    void                tp_message_set_uint64               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             guint64 u);

    TpMessage *         tp_message_new                      (TpBaseConnection *connection,
                                                             guint initial_parts,
                                                             guint size_hint);
    void                tp_message_destroy                  (TpMessage *self);
    void                tp_message_ref_handle               (TpMessage *self,
                                                             TpHandleType handle_type,
                                                             TpHandle handle);
    void                tp_message_set_handle               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             TpHandleType handle_type,
                                                             TpHandle handle_or_0);
    void                tp_message_take_message             (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             TpMessage *message);

## Object Hierarchy

      GObject
       +----TpMessage
             +----TpClientMessage
             +----TpCMMessage
             +----TpSignalledMessage

## Description

TpMessage represent a message send or received using the Message interface.

## Details

### TpMessage

    typedef struct _TpMessage TpMessage;

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

This base class provides convenience API for most of the common keys that can appear in the header. One notable exception is the sender of the message. Inside a connection manager, messages are represented by the TpCMMessage subclass, and you should use `tp_cm_message_get_sender()`. When composing a message in a client using TpClientMessage, messages do not have an explicit sender (the sender is automatically the local user). When a client sees a sent or received message signalled by the connection manager (represented by TpSignalledMessage), the message's sender (if any) can be accessed with `tp_signalled_message_get_sender()`.

### tp_message_count_parts ()

    guint               tp_message_count_parts              (TpMessage *self);

`self` : | a message
Returns : | the number of parts in the message, including the headers in part 0

Since 0.7.21

### tp_message_dup_part ()

    GVariant *          tp_message_dup_part                 (TpMessage *self,
                                                             guint part);

`self` : | a message
`part` : | a part number
Returns : | the current contents of the given part, or `NULL` if the part number is out of range. [transfer full]

Since 0.19.10

### tp_message_peek ()

    const GHashTable *  tp_message_peek                     (TpMessage *self,
                                                             guint part);

`self` : | a message
`part` : | a part number
Returns : | the GHashTable used to implement the given part, or `NULL` if the part number is out of range. The hash table is only valid as long as the message is valid and the part is not deleted. [transfer none][element-type utf8 GObject.Value]

Since 0.7.21

### tp_message_to_text ()

    gchar *             tp_message_to_text                  (TpMessage *message,
                                                             TpChannelTextMessageFlags *out_flags);

Concatene all the text parts contained in `message`.

`message` : | a TpMessage
`out_flags` : | (out) : if not `NULL`, the TpChannelTextMessageFlags of `message`
Returns : | a newly allocated string containing the text content of message. [transfer full]

Since 0.13.9

### tp_message_get_message_type ()

    TpChannelTextMessageType tp_message_get_message_type    (TpMessage *self);

`self` : | a message
Returns : | the type of this message

Since 0.13.10

### tp_message_get_received_timestamp ()

    gint64              tp_message_get_received_timestamp   (TpMessage *self);

Return when this message was received locally, as a number of seconds since the beginning of 1970 in the UTC timezone (the same representation used by `g_date_time_new_from_unix_utc()`, for instance), or 0 if not known.

`self` : | a message
Returns : | a Unix timestamp, or 0

Since 0.13.9

### tp_message_get_sent_timestamp ()

    gint64              tp_message_get_sent_timestamp       (TpMessage *self);

Return when this message was sent, as a number of seconds since the beginning of 1970 in the UTC timezone (the same representation used by `g_date_time_new_from_unix_utc()`, for instance), or 0 if not known.

If this protocol does not track the time at which the message was initially sent, this timestamp might be approximated by using the time at which it arrived at a central server.

`self` : | a message
Returns : | a Unix timestamp, or 0

Since 0.13.9

### tp_message_get_specific_to_interface ()

    const gchar *       tp_message_get_specific_to_interface
                                                            (TpMessage *self);

If this message is specific to a particular D-Bus interface and should be ignored by clients without knowledge of that interface, return the name of the interface.

If this message is an ordinary message or delivery report, return `NULL`.

`self` : | a message
Returns : | a D-Bus interface name, or `NULL` for ordinary messages and delivery reports. [transfer none]

Since 0.13.9

### tp_message_get_supersedes ()

    const gchar *       tp_message_get_supersedes           (TpMessage *self);

If this message replaces a previous message, return the value of `tp_message_get_token()` for that previous message. Otherwise, return `NULL`.

For instance, a user interface could replace the superseded message with this message, or grey out the superseded message.

`self` : | a message
Returns : | a non-empty opaque identifier, or `NULL` if none. [transfer none]

Since 0.13.9

### tp_message_get_token ()

    const gchar *       tp_message_get_token                (TpMessage *self);

Return this message's identifier in the underlying protocol. This is not guaranteed to be unique, even within the scope of a single channel or contact: the only guarantee made is that two messages with different non-empty tokens are different messages.

If there is no suitable token, return `NULL`.

`self` : | a message
Returns : | a non-empty opaque identifier, or `NULL` if none. [transfer none]

Since 0.13.9

### tp_message_is_delivery_report ()

    gboolean            tp_message_is_delivery_report       (TpMessage *self);

If this message is a delivery report indicating success or failure of delivering a message, return `TRUE`.

`self` : | a message
Returns : | `TRUE` if this is a delivery report

Since 0.13.9

### tp_message_is_rescued ()

    gboolean            tp_message_is_rescued               (TpMessage *self);

Returns `TRUE` if this incoming message has been seen in a previous channel during the lifetime of the Connection, but had not been acknowledged when that channel closed, causing an identical channel (in which the message now appears) to open.

Loggers should check this flag to avoid duplicating messages, for instance.

`self` : | a message
Returns : | `TRUE` if this message was seen in a previous Channel on this Connection

Since 0.13.9

### tp_message_is_scrollback ()

    gboolean            tp_message_is_scrollback            (TpMessage *self);

`self` : | a message
Returns : | `TRUE` if this message is part of a replay of message history, for instance in an XMPP chatroom.

Since 0.13.9

### tp_message_get_pending_message_id ()

    guint32             tp_message_get_pending_message_id   (TpMessage *self,
                                                             gboolean *valid);

Return the incoming message ID of `self`. Only incoming messages have such ID, for outgoing ones this function returns 0 and set `valid` to `FALSE`.

`self` : | a message
`valid` : | either `NULL`, or a location in which to store `TRUE` if `self` contains a pending message ID. [out]
Returns : | the incoming message ID.

Since 0.15.3

### tp_message_is_mutable ()

    gboolean            tp_message_is_mutable               (TpMessage *self);

Check if `self` is mutable. Only mutable messages can be modified using functions such as `tp_message_set_string()`.

`self` : | a TpMessage
Returns : | `TRUE` if the message is mutable.

Since 0.13.9

### tp_message_append_part ()

    guint               tp_message_append_part              (TpMessage *self);

Append a body part to the message.

`self` : | a message
Returns : | the part number

Since 0.7.21

### tp_message_delete_key ()

    gboolean            tp_message_delete_key               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key);

Remove the given key and its value from the given 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
Returns : | `TRUE` if the key previously existed

Since 0.7.21

### tp_message_delete_part ()

    void                tp_message_delete_part              (TpMessage *self,
                                                             guint part);

Delete the given body part from the message.

`self` : | a message
`part` : | a part number, which must be strictly greater than 0, and strictly less than the number returned by `tp_message_count_parts()`

Since 0.7.21

### tp_message_set ()

    void                tp_message_set                      (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             const GValue *source);

Set `key` in part `part` of `self` to have a copy of `source` as its value.

If `source` represents a data structure containing handles, they should all be referenced with `tp_message_ref_handle()` first.

In high-level language bindings, use `tp_message_set_variant()` instead.

`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
`source` : | a value, encoded as dbus-glib would

Since 0.7.21

### tp_message_set_variant ()

    void                tp_message_set_variant              (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             GVariant *value);

Set `key` in part `part` of `self` to have `value` as its value.

If `value` is a floating reference (see `g_variant_ref_sink()`), then this function will take ownership of it.

`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
`value` : | a value

Since 0.19.10

### tp_message_set_boolean ()

    void                tp_message_set_boolean              (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             gboolean b);

Set `key` in part `part` of `self` to have `b` as a boolean value.

`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
`b` : | a boolean value

Since 0.7.21

### tp_message_set_bytes ()

    void                tp_message_set_bytes                (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             guint len,
                                                             gconstpointer bytes);

Set `key` in part `part` of `self` to have `bytes` as a byte-array value.

`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
`len` : | a number of bytes
`bytes` : | an array of `len` bytes

Since 0.7.21

### tp_message_set_int16()

    #define             tp_message_set_int16(s, p, k, i)

Set `key` in part `part` of `self` to have `i` as a signed integer value.

`s` : | a message
`p` : | a part number, which must be strictly less than the number returned by `tp_message_count_parts()`
`k` : | a key in the mapping representing the part
`i` : | an integer value

Since 0.7.21

### tp_message_set_int32 ()

    void                tp_message_set_int32                (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             gint32 i);

Set `key` in part `part` of `self` to have `i` as a signed integer value.

`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
`i` : | an integer value

Since 0.7.21

### tp_message_set_int64 ()

    void                tp_message_set_int64                (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             gint64 i);

Set `key` in part `part` of `self` to have `i` as a signed integer value.

`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
`i` : | an integer value

Since 0.7.21

### tp_message_set_string ()

    void                tp_message_set_string               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             const gchar *s);

Set `key` in part `part` of `self` to have `s` as a string value.

`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
`s` : | a string value

Since 0.7.21

### tp_message_set_string_printf ()

    void                tp_message_set_string_printf        (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             const gchar *fmt,
                                                             ...);

Set `key` in part `part` of `self` to have a string value constructed from a printf-style format string.

`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
`fmt` : | a printf-style format string for the string value
`...` : | arguments for the format string

Since 0.7.21

### tp_message_set_uint16()

    #define             tp_message_set_uint16(s, p, k, u)

Set `key` in part `part` of `self` to have `u` as an unsigned integer value.

`s` : | a message
`p` : | a part number, which must be strictly less than the number returned by `tp_message_count_parts()`
`k` : | a key in the mapping representing the part
`u` : | an unsigned integer value

Since 0.7.21

### tp_message_set_uint32 ()

    void                tp_message_set_uint32               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             guint32 u);

Set `key` in part `part` of `self` to have `u` as an unsigned integer value.

`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
`u` : | an unsigned integer value

Since 0.7.21

### tp_message_set_uint64 ()

    void                tp_message_set_uint64               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             guint64 u);

Set `key` in part `part` of `self` to have `u` as an unsigned integer value.

`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
`u` : | an unsigned integer value

Since 0.7.21

### tp_message_new ()

    TpMessage *         tp_message_new                      (TpBaseConnection *connection,
                                                             guint initial_parts,
                                                             guint size_hint);

### Warning

`tp_message_new` is deprecated and should not be used in newly-written code. since 0.13.9. Use `tp_cm_message_new()`

`connection` : | a connection on which to reference handles
`initial_parts` : | number of parts to create (at least 1)
`size_hint` : | preallocate space for this many parts (at least `initial_parts`)
Returns : | a newly allocated message suitable to be passed to `tp_message_mixin_take_received()`

Since 0.7.21

### tp_message_destroy ()

    void                tp_message_destroy                  (TpMessage *self);

Since 0.13.9 this function is a simple wrapper around `g_object_unref()`

`self` : | a message

Since 0.7.21

### tp_message_ref_handle ()

    void                tp_message_ref_handle               (TpMessage *self,
                                                             TpHandleType handle_type,
                                                             TpHandle handle);

### Warning

`tp_message_ref_handle` is deprecated and should not be used in newly-written code. since 0.13.9. Handles are now immortal so there is no point to ref them. Furthermore, the only handle that should be stored in a TpMessage is message-sender which should be set using `tp_cm_message_set_sender()`.

Reference the given handle until this message is destroyed.

`self` : | a message
`handle_type` : | a handle type, greater than `TP_HANDLE_TYPE_NONE` and less than `TP_NUM_HANDLE_TYPES`
`handle` : | a handle of the given type

Since 0.7.21

### tp_message_set_handle ()

    void                tp_message_set_handle               (TpMessage *self,
                                                             guint part,
                                                             const gchar *key,
                                                             TpHandleType handle_type,
                                                             TpHandle handle_or_0);

### Warning

`tp_message_set_handle` is deprecated and should not be used in newly-written code. since 0.13.9. Use `tp_cm_message_set_sender()`

If `handle_or_0` is not zero, reference it with `tp_message_ref_handle()`.

Set `key` in part `part` of `self` to have `handle_or_0` as an unsigned integer value.

Since 0.13.9 this function has been deprecated in favor or `tp_cm_message_set_sender()` as 'message-sender' is the only handle you can put in a TpCMMessage.

`self` : | a TpCMMessage
`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
`handle_type` : | a handle type
`handle_or_0` : | a handle of that type, or 0

Since 0.7.21

### tp_message_take_message ()

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

### Warning

`tp_message_take_message` is deprecated and should not be used in newly-written code. since 0.13.9. Use `tp_cm_message_take_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 TpCMMessage
`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.7.21

## See Also

TpCMMessage, TpClientMessage, TpSignalledMessage