TelepathyGLib.TextChannel¶

Subclasses:: None

Methods¶

Inherited:: TelepathyGLib.Channel (44), TelepathyGLib.Proxy (11), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`get_feature_quark_chat_states` ()
class	`get_feature_quark_incoming_messages` ()
class	`get_feature_quark_sms` ()
class	`new` (conn, object_path, immutable_properties)
	`ack_all_pending_messages_async` (callback, *user_data)
	`ack_all_pending_messages_finish` (result)
	`ack_message_async` (message, callback, *user_data)
	`ack_message_finish` (result)
	`ack_messages_async` (messages, callback, *user_data)
	`ack_messages_finish` (result)
	`dup_pending_messages` ()
	`get_chat_state` (contact)
	`get_delivery_reporting_support` ()
	`get_message_part_support_flags` ()
	`get_message_types` ()
	`get_pending_messages` ()
	`get_sms_flash` ()
	`get_sms_length_async` (message, callback, *user_data)
	`get_sms_length_finish` (result)
	`get_supported_content_types` ()
	`is_sms_channel` ()
	`send_message_async` (message, flags, callback, *user_data)
	`send_message_finish` (result)
	`set_chat_state_async` (state, callback, *user_data)
	`set_chat_state_finish` (result)
	`supports_message_type` (message_type)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Inherited:: TelepathyGLib.Channel (12), TelepathyGLib.Proxy (5)

Name	Type	Flags	Short Description
`delivery-reporting-support`	`int`	r	The Messages.DeliveryReportingSupport property of the channel
`is-sms-channel`	`bool`	r	The SMS.SMSChannel property of the channel
`message-part-support-flags`	`int`	r	The Messages.MessagePartSupportFlags property of the channel
`sms-flash`	`bool`	r	The SMS.Flash property of the channel
`supported-content-types`	[`str`]	r	The Messages.SupportedContentTypes property of the channel

Signals¶

Inherited:: TelepathyGLib.Channel (5), TelepathyGLib.Proxy (2), GObject.Object (1)

Name	Short Description
`contact-chat-state-changed`	Emitted when a contact’s chat state changes after `TelepathyGLib.Proxy.prepare_async`() has finished preparing features %TP_TEXT_CHANNEL_FEATURE_CHAT_STATES, %TP_CHANNEL_FEATURE_GROUP and %TP_CHANNEL_FEATURE_CONTACTS.
`message-received`	The `::message-received` signal is emitted when a new message has been received on self.
`message-sent`	The `::message-sent` signal is emitted when message has been submitted for sending.
`pending-message-removed`	The `::pending-message-removed` signal is emitted when message has been acked and so removed from the pending messages list.

Fields¶

Inherited:: TelepathyGLib.Channel (5), TelepathyGLib.Proxy (2), GObject.Object (1)

Name	Type	Access	Description
parent	`TelepathyGLib.Channel`	r

Class Details¶

class TelepathyGLib.TextChannel(**kwargs)¶

Bases:: TelepathyGLib.Channel
Abstract:: No
Structure:: TelepathyGLib.TextChannelClass

Data structure representing a TelepathyGLib.TextChannel.

New in version 0.13.10.

classmethod get_feature_quark_chat_states()¶

Return type:: int

classmethod get_feature_quark_incoming_messages()¶

Return type:: int

classmethod get_feature_quark_sms()¶

Return type:: int

classmethod new(conn, object_path, immutable_properties)¶

Parameters:

conn (TelepathyGLib.Connection) – a TelepathyGLib.Connection; may not be None
object_path (str) – the object path of the channel; may not be None
immutable_properties ({str: GObject.Value}) – the immutable properties of the channel, as signalled by the NewChannel D-Bus signal or returned by the CreateChannel and EnsureChannel D-Bus methods: a mapping from strings (D-Bus interface name + “.” + property name) to GObject.Value instances

Raises:

GLib.Error

Returns:

a newly created TelepathyGLib.TextChannel

Return type:

TelepathyGLib.TextChannel

Convenient function to create a new TelepathyGLib.TextChannel

New in version 0.13.10.

Deprecated since version ???: Use TelepathyGLib.SimpleClientFactory.ensure_channel() instead.

ack_all_pending_messages_async(callback, *user_data)¶

Parameters:

callback (Gio.AsyncReadyCallback or None) – a callback to call when the messages have been acked
user_data (object or None) – data to pass to callback

Acknowledge all the pending messages. This is equivalent of calling TelepathyGLib.TextChannel.ack_messages_async() with the list of TelepathyGLib.SignalledMessage returned by TelepathyGLib.TextChannel.dup_pending_messages().

Once the messages have been acked, callback will be called. You can then call TelepathyGLib.TextChannel.ack_all_pending_messages_finish() to get the result of the operation.

See TelepathyGLib.TextChannel.ack_message_async() about acknowledging messages.

New in version 0.15.3.

ack_all_pending_messages_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the messages have been acked, False otherwise.
Return type:: bool

Finish an asynchronous acknowledgement operation of all messages.

New in version 0.15.3.

ack_message_async(message, callback, *user_data)¶

Parameters:

message (TelepathyGLib.Message) – a TelepathyGLib.SignalledMessage
callback (Gio.AsyncReadyCallback or None) – a callback to call when the message have been acked
user_data (object or None) – data to pass to callback

Acknowledge message. Once the message has been acked, callback will be called. You can then call TelepathyGLib.TextChannel.ack_message_finish() to get the result of the operation.

A message should be acknowledged once it has been shown to the user by the Handler of the channel. So Observers and Approvers should NOT acknowledge messages themselves. Once a message has been acknowledged, it is removed from the pending-message queue and so the TelepathyGLib.TextChannel ::pending-message-removed signal is fired.

You should use the TelepathyGLib.SignalledMessage received from TelepathyGLib.TextChannel.dup_pending_messages() or the TelepathyGLib.TextChannel ::message-received signal.

New in version 0.13.10.

ack_message_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.TextChannel.ack_message_async()
Raises:: GLib.Error
Returns:: True if the message has been acked, False otherwise.
Return type:: bool

Finishes acknowledging a message.

New in version 0.13.10.

ack_messages_async(messages, callback, *user_data)¶

Parameters:

messages ([TelepathyGLib.SignalledMessage]) – a GLib.List of TelepathyGLib.SignalledMessage
callback (Gio.AsyncReadyCallback or None) – a callback to call when the message have been acked
user_data (object or None) – data to pass to callback

Acknowledge all the messages in messages. Once the messages have been acked, callback will be called. You can then call TelepathyGLib.TextChannel.ack_messages_finish() to get the result of the operation.

You should use the TelepathyGLib.SignalledMessage received from TelepathyGLib.TextChannel.dup_pending_messages() or the TelepathyGLib.TextChannel ::message-received signal.

See TelepathyGLib.TextChannel.ack_message_async() about acknowledging messages.

New in version 0.13.10.

ack_messages_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.TextChannel.ack_messages_async()
Raises:: GLib.Error
Returns:: True if the messages have been acked, False otherwise.
Return type:: bool

Finishes acknowledging a list of messages.

New in version 0.13.10.

dup_pending_messages()¶

Returns:: a GLib.List of reffed TelepathyGLib.SignalledMessage
Return type:: [TelepathyGLib.SignalledMessage]

Return a newly allocated list of unacknowledged TelepathyGLib.SignalledMessage objects.

It is guaranteed that the TelepathyGLib.SignalledMessage :sender of each TelepathyGLib.SignalledMessage has all of the features previously passed to TelepathyGLib.SimpleClientFactory.add_contact_features() prepared.

New in version 0.19.9.

get_chat_state(contact)¶

Parameters:: contact (TelepathyGLib.Contact) – a TelepathyGLib.Contact
Returns:: the chat state for contact, or TelepathyGLib.ChannelChatState.INACTIVE if their chat state is not known
Return type:: TelepathyGLib.ChannelChatState

Return the chat state for the given contact. If TelepathyGLib.Proxy.is_prepared() would return False for the feature %TP_TEXT_CHANNEL_FEATURE_CHAT_STATES, the result will always be TelepathyGLib.ChannelChatState.INACTIVE.

New in version 0.19.0.

get_delivery_reporting_support()¶

Returns:: the value of TelepathyGLib.TextChannel :delivery-reporting-support property
Return type:: TelepathyGLib.DeliveryReportingSupportFlags

Return the TelepathyGLib.TextChannel :delivery-reporting-support property

New in version 0.13.10.

get_message_part_support_flags()¶

Returns:: the value of TelepathyGLib.TextChannel :message-part-support-flags
Return type:: TelepathyGLib.MessagePartSupportFlags

Return the TelepathyGLib.TextChannel :message-part-support-flags property

New in version 0.13.10.

get_message_types()¶

Returns:: the value of TelepathyGLib.TextChannel :message-types
Return type:: [TelepathyGLib.ChannelTextMessageType]

Return the TelepathyGLib.TextChannel :message-types property

New in version 0.13.16.

get_pending_messages()¶

Returns:: a GLib.List of borrowed TelepathyGLib.SignalledMessage
Return type:: [TelepathyGLib.SignalledMessage]

Return a newly allocated list of unacknowledged TelepathyGLib.SignalledMessage objects.

It is guaranteed that the TelepathyGLib.SignalledMessage :sender of each TelepathyGLib.SignalledMessage has all of the features previously passed to TelepathyGLib.SimpleClientFactory.add_contact_features() prepared.

New in version 0.13.10.

Deprecated since version 0.19.9: New code should use TelepathyGLib.TextChannel.dup_pending_messages() instead.

get_sms_flash()¶

Returns:: the value of TelepathyGLib.TextChannel :sms-flash property
Return type:: bool

Return the TelepathyGLib.TextChannel :sms-flash property

New in version 0.15.1.

get_sms_length_async(message, callback, *user_data)¶

Parameters:

message (TelepathyGLib.Message) – a TelepathyGLib.ClientMessage
callback (Gio.AsyncReadyCallback or None) – a callback to call when the request has been satisfied
user_data (object or None) – data to pass to callback

Starts an async call to get the number of 140 octet chunks required to send a #message via SMS on #self, as well as the number of remaining characters available in the final chunk and, if possible, an estimate of the cost.

Once the request has been satisfied, callback will be called. You can then call TelepathyGLib.TextChannel.get_sms_length_finish() to get the result of the operation.

New in version 0.15.1.

get_sms_length_finish(result)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if the number of 140 octet chunks required to send the message has been retrieved, False otherwise.

chunks_required:: if not None used to return the number of 140 octet chunks required to send the message.
remaining_characters:: if not None used to return the number of further characters that can be fit in the final chunk. A negative value indicates that the message will be truncated by abs(remaining_characters). The value GObject.G_MININT32 indicates the message will be truncated by an unknown amount.
estimated_cost:: if not None used to return the estimated cost of sending this message. The currency and scale of this value are the same as the values of the TelepathyGLib.Connection :balance-scale and TelepathyGLib.Connection :balance-currency properties. A value of -1 indicates the cost could not be estimated.

Return type:

(bool, chunks_required: int, remaining_characters: int, estimated_cost: int)

Finishes an async SMS length request.

New in version 0.15.1.

get_supported_content_types()¶

Returns:: the value of TelepathyGLib.TextChannel :supported-content-types
Return type:: [str]

Return the TelepathyGLib.TextChannel :supported-content-types property

New in version 0.13.10.

is_sms_channel()¶

Returns:: the value of TelepathyGLib.TextChannel :is-sms-channel property
Return type:: bool

Return the TelepathyGLib.TextChannel :is-sms-channel property

New in version 0.15.1.

send_message_async(message, flags, callback, *user_data)¶

Parameters:

message (TelepathyGLib.Message) – a TelepathyGLib.ClientMessage
flags (TelepathyGLib.MessageSendingFlags) – flags affecting how the message is sent
callback (Gio.AsyncReadyCallback or None) – a callback to call when the message has been submitted to the server
user_data (object or None) – data to pass to callback

Submit a message to the server for sending. Once the message has been submitted to the sever, callback will be called. You can then call TelepathyGLib.TextChannel.send_message_finish() to get the result of the operation.

New in version 0.13.10.

send_message_finish(result)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.TextChannel.send_message_async()

Raises:

GLib.Error

Returns:

True if the message has been submitted to the server, False otherwise.

token:: if not None, used to return the token of the sent message

Return type:

(bool, token: str)

Completes a call to TelepathyGLib.TextChannel.send_message_async().

token can be used to match any incoming delivery or failure reports against the sent message. If this function returns true but the returned token is None, the message was sent successfully but the protocol does not provide a way to identify it later.

New in version 0.13.10.

set_chat_state_async(state, callback, *user_data)¶

Parameters:

state (TelepathyGLib.ChannelChatState) – a TelepathyGLib.ChannelChatState to set
callback (Gio.AsyncReadyCallback or None) – a callback to call when the chat state has been set
user_data (object or None) – data to pass to callback

Set the local state on channel self to state. Once the state has been set, callback will be called. You can then call TelepathyGLib.TextChannel.set_chat_state_finish() to get the result of the operation.

New in version 0.13.10.

set_chat_state_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.TextChannel.set_chat_state_async()
Raises:: GLib.Error
Returns:: True if the chat state has been changed, False otherwise.
Return type:: bool

Completes a call to TelepathyGLib.TextChannel.set_chat_state_async().

New in version 0.13.10.

supports_message_type(message_type)¶

Parameters:: message_type (TelepathyGLib.ChannelTextMessageType) – a TelepathyGLib.ChannelTextMessageType
Returns:: True if message of type message_type can be sent on self, False otherwise
Return type:: bool

Check if message of type message_type can be sent on this channel.

New in version 0.13.16.

Signal Details¶

TelepathyGLib.TextChannel.signals.contact_chat_state_changed(text_channel, contact, state)¶

Signal Name:

contact-chat-state-changed

Flags:

RUN_LAST, DETAILED

Parameters:

text_channel (TelepathyGLib.TextChannel) – The object which received the signal
contact (TelepathyGLib.Contact) – a TelepathyGLib.Contact for the local user or another contact
state (int) – the new TelepathyGLib.ChannelChatState for the contact

Emitted when a contact’s chat state changes after TelepathyGLib.Proxy.prepare_async() has finished preparing features %TP_TEXT_CHANNEL_FEATURE_CHAT_STATES, %TP_CHANNEL_FEATURE_GROUP and %TP_CHANNEL_FEATURE_CONTACTS.

New in version 0.19.0.

TelepathyGLib.TextChannel.signals.message_received(text_channel, message)¶

Signal Name:

message-received

Flags:

RUN_LAST

Parameters:

text_channel (TelepathyGLib.TextChannel) – The object which received the signal
message (TelepathyGLib.SignalledMessage) – a TelepathyGLib.SignalledMessage

The ::message-received signal is emitted when a new message has been received on self.

The same message object will be used by the TelepathyGLib.TextChannel ::pending-message-removed signal once message has been acked so you can simply compare pointers to identify the message.

Note that this signal is only fired once the #TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES has been prepared.

It is guaranteed that message's TelepathyGLib.SignalledMessage :sender has all of the features previously passed to TelepathyGLib.SimpleClientFactory.add_contact_features() prepared.

New in version 0.13.10.

TelepathyGLib.TextChannel.signals.message_sent(text_channel, message, flags, token)¶

Signal Name:

message-sent

Flags:

RUN_LAST

Parameters:

text_channel (TelepathyGLib.TextChannel) – The object which received the signal
message (TelepathyGLib.SignalledMessage) – a TelepathyGLib.SignalledMessage
flags (int) – the TelepathyGLib.MessageSendingFlags affecting how the message was sent
token (str) – an opaque token used to match any incoming delivery or failure reports against this message, or None if the message is not readily identifiable.

The ::message-sent signal is emitted when message has been submitted for sending.

It is guaranteed that message's TelepathyGLib.SignalledMessage :sender has all of the features previously passed to TelepathyGLib.SimpleClientFactory.add_contact_features() prepared.

New in version 0.13.10.

TelepathyGLib.TextChannel.signals.pending_message_removed(text_channel, message)¶

Signal Name:

pending-message-removed

Flags:

RUN_LAST

Parameters:

text_channel (TelepathyGLib.TextChannel) – The object which received the signal
message (TelepathyGLib.SignalledMessage) – a TelepathyGLib.SignalledMessage

The ::pending-message-removed signal is emitted when message has been acked and so removed from the pending messages list.

Note that this signal is only fired once the #TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES has been prepared.

It is guaranteed that message's TelepathyGLib.SignalledMessage :sender has all of the features previously passed to TelepathyGLib.SimpleClientFactory.add_contact_features() prepared.

New in version 0.13.10.

Property Details¶

TelepathyGLib.TextChannel.props.delivery_reporting_support¶

Name:: delivery-reporting-support
Type:: int
Default Value:: 0
Flags:: READABLE

A TelepathyGLib.DeliveryReportingSupportFlags indicating features supported by this channel.

New in version 0.13.10.

TelepathyGLib.TextChannel.props.is_sms_channel¶

Name:: is-sms-channel
Type:: bool
Default Value:: False
Flags:: READABLE

True if messages sent and received on this channel are transmitted via SMS.

This property is not guaranteed to have a meaningful value until TP_TEXT_CHANNEL_FEATURE_SMS has been prepared.

New in version 0.15.1.

TelepathyGLib.TextChannel.props.message_part_support_flags¶

Name:: message-part-support-flags
Type:: int
Default Value:: 0
Flags:: READABLE

A TelepathyGLib.MessagePartSupportFlags indicating the level of support for message parts on this channel.

New in version 0.13.10.

TelepathyGLib.TextChannel.props.sms_flash¶

Name:: sms-flash
Type:: bool
Default Value:: False
Flags:: READABLE

True if this channel is exclusively for receiving class 0 SMSes (and no SMSes can be sent using TelepathyGLib.TextChannel.send_message_async() on this channel). If False, no incoming class 0 SMSes will appear on this channel.

New in version 0.15.1.

TelepathyGLib.TextChannel.props.supported_content_types¶

Name:: supported-content-types
Type:: [str]
Default Value:: []
Flags:: READABLE

A #GStrv containing the MIME types supported by this channel, with more preferred MIME types appearing earlier in the array.

New in version 0.13.10.