TelepathyGLib.Message¶

Subclasses:: TelepathyGLib.ClientMessage, TelepathyGLib.SignalledMessage

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`append_part` ()
	`count_parts` ()
	`delete_key` (part, key)
	`delete_part` (part)
	`destroy` ()
	`dup_part` (part)
	`get_message_type` ()
	`get_pending_message_id` ()
	`get_received_timestamp` ()
	`get_sent_timestamp` ()
	`get_specific_to_interface` ()
	`get_supersedes` ()
	`get_token` ()
	`is_delivery_report` ()
	`is_mutable` ()
	`is_rescued` ()
	`is_scrollback` ()
	`peek` (part)
	`ref_handle` (handle_type, handle)
	`set` (part, key, source)
	`set_boolean` (part, key, b)
	`set_bytes` (part, key, len, bytes)
	`set_handle` (part, key, handle_type, handle_or_0)
	`set_int32` (part, key, i)
	`set_int64` (part, key, i)
	`set_string` (part, key, s)
	`set_uint32` (part, key, u)
	`set_uint64` (part, key, u)
	`set_variant` (part, key, value)
	`take_message` (part, key, message)
	`to_text` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class TelepathyGLib.Message(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: TelepathyGLib.MessageClass

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 TelepathyGLib.ClientMessage, 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 TelepathyGLib.SignalledMessage), the message’s sender (if any) can be accessed with TelepathyGLib.SignalledMessage.get_sender().

append_part()¶

Returns:: the part number
Return type:: int

Append a body part to the message.

New in version 0.7.21.

count_parts()¶

Returns:: the number of parts in the message, including the headers in part 0
Return type:: int

nothing more to say

New in version 0.7.21.

delete_key(part, key)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part

Returns:

True if the key previously existed

Return type:

bool

Remove the given key and its value from the given part.

New in version 0.7.21.

delete_part(part)¶

Parameters:: part (int) – a part number, which must be strictly greater than 0, and strictly less than the number returned by TelepathyGLib.Message.count_parts()

Delete the given body part from the message.

New in version 0.7.21.

destroy()¶: Since 0.13.9 this function is a simple wrapper around GObject.Object.unref()

New in version 0.7.21.

dup_part(part)¶

Parameters:: part (int) – a part number
Returns:: the current contents of the given part, or None if the part number is out of range
Return type:: GLib.Variant

nothing more to say

New in version 0.19.10.

get_message_type()¶

Returns:: the type of this message
Return type:: TelepathyGLib.ChannelTextMessageType

New in version 0.13.10.

get_pending_message_id()¶

Returns:

the incoming message ID.

valid:: either None, or a location in which to store True if self contains a pending message ID.

Return type:

(int, valid: bool)

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.

New in version 0.15.3.

get_received_timestamp()¶

Returns:: a Unix timestamp, or 0
Return type:: int

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 GLib.DateTime.new_from_unix_utc(), for instance), or 0 if not known.

New in version 0.13.9.

get_sent_timestamp()¶

Returns:: a Unix timestamp, or 0
Return type:: int

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

New in version 0.13.9.

get_specific_to_interface()¶

Returns:: a D-Bus interface name, or None for ordinary messages and delivery reports
Return type:: str

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

New in version 0.13.9.

get_supersedes()¶

Returns:: a non-empty opaque identifier, or None if none
Return type:: str

If this message replaces a previous message, return the value of TelepathyGLib.Message.get_token() for that previous message. Otherwise, return None.

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

New in version 0.13.9.

get_token()¶

Returns:: a non-empty opaque identifier, or None if none
Return type:: str

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

New in version 0.13.9.

is_delivery_report()¶

Returns:: True if this is a delivery report
Return type:: bool

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

New in version 0.13.9.

is_mutable()¶

Returns:: True if the message is mutable.
Return type:: bool

Check if self is mutable. Only mutable messages can be modified using functions such as TelepathyGLib.Message.set_string().

New in version 0.13.9.

is_rescued()¶

Returns:: True if this message was seen in a previous Channel on this Connection
Return type:: bool

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.

New in version 0.13.9.

is_scrollback()¶

Returns:: True if this message is part of a replay of message history, for instance in an XMPP chatroom.
Return type:: bool

no more to say

New in version 0.13.9.

peek(part)¶

Parameters:: part (int) – a part number
Returns:: the GLib.HashTable used to implement the given part, or None 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.
Return type:: {str: GObject.Value}

nothing more to say

New in version 0.7.21.

ref_handle(handle_type, handle)¶

Parameters:

handle_type (TelepathyGLib.HandleType) – a handle type, greater than TelepathyGLib.HandleType.NONE and less than TelepathyGLib.NUM_HANDLE_TYPES
handle (int) – a handle of the given type

Reference the given handle until this message is destroyed.

New in version 0.7.21.

Deprecated since version ???: 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 TelepathyGLib.Message is message-sender which should be set using tp_cm_message_set_sender().

set(part, key, source)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
source (GObject.Value) – a value, encoded as dbus-glib would

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 TelepathyGLib.Message.ref_handle() first.

In high-level language bindings, use TelepathyGLib.Message.set_variant() instead.

New in version 0.7.21.

set_boolean(part, key, b)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
b (bool) – a boolean value

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

New in version 0.7.21.

set_bytes(part, key, len, bytes)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
len (int) – a number of bytes
bytes (object or None) – an array of len bytes

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

New in version 0.7.21.

set_handle(part, key, handle_type, handle_or_0)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
handle_type (TelepathyGLib.HandleType) – a handle type
handle_or_0 (int) – a handle of that type, or 0

If handle_or_0 is not zero, reference it with TelepathyGLib.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.

New in version 0.7.21.

Deprecated since version ???: since 0.13.9. Use tp_cm_message_set_sender()

set_int32(part, key, i)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
i (int) – an integer value

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

New in version 0.7.21.

set_int64(part, key, i)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
i (int) – an integer value

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

New in version 0.7.21.

set_string(part, key, s)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
s (str) – a string value

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

New in version 0.7.21.

set_uint32(part, key, u)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
u (int) – an unsigned integer value

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

New in version 0.7.21.

set_uint64(part, key, u)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
u (int) – an unsigned integer value

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

New in version 0.7.21.

set_variant(part, key, value)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
value (GLib.Variant) – a value

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

If value is a floating reference (see GLib.Variant.ref_sink()), then this function will take ownership of it.

New in version 0.19.10.

take_message(part, key, message)¶

Parameters:

part (int) – a part number, which must be strictly less than the number returned by TelepathyGLib.Message.count_parts()
key (str) – a key in the mapping representing the part
message (TelepathyGLib.Message) – another (distinct) message created for the same TelepathyGLib.BaseConnection

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.

New in version 0.7.21.

Deprecated since version ???: since 0.13.9. Use tp_cm_message_take_message()

to_text()¶

Returns:

a newly allocated string containing the text content of #message

out_flags:: if not None, the TelepathyGLib.ChannelTextMessageFlags of self

Return type:

(str, out_flags: TelepathyGLib.ChannelTextMessageFlags)

Concatene all the text parts contained in self.

New in version 0.13.9.