TpMessage

TpMessage — a message in the Telepathy message interface

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── TpMessage
        ├── TpClientMessage
        ├── TpCMMessage
        ╰── TpSignalledMessage

Includes

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

Description

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

Functions

tp_message_count_parts ()

guint
tp_message_count_parts (TpMessage *self);

Parameters

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

Parameters

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

Parameters

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 .

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

tp_message_new is deprecated and should not be used in newly-written code.

since 0.13.9. Use tp_cm_message_new()

Parameters

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

Parameters

self

a message

 

Since: 0.7.21


tp_message_ref_handle ()

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

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.

Parameters

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

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.

Parameters

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

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 .

Parameters

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

Types and Values

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

See Also

TpCMMessage, TpClientMessage, TpSignalledMessage