TelepathyGLib.Channel¶

Subclasses:: TelepathyGLib.CallChannel, TelepathyGLib.DBusTubeChannel, TelepathyGLib.FileTransferChannel, TelepathyGLib.StreamTubeChannel, TelepathyGLib.TextChannel

Methods¶

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

class	`get_feature_quark_chat_states` ()
class	`get_feature_quark_contacts` ()
class	`get_feature_quark_core` ()
class	`get_feature_quark_group` ()
class	`get_feature_quark_password` ()
class	`init_known_interfaces` ()
class	`new` (conn, object_path, optional_channel_type, optional_handle_type, optional_handle)
class	`new_from_properties` (conn, object_path, immutable_properties)
	`borrow_connection` ()
	`borrow_immutable_properties` ()
	`close_async` (callback, *user_data)
	`close_finish` (result)
	`destroy_async` (callback, *user_data)
	`destroy_finish` (result)
	`dup_immutable_properties` ()
	`get_channel_type` ()
	`get_channel_type_id` ()
	`get_chat_state` (contact)
	`get_connection` ()
	`get_handle` ()
	`get_identifier` ()
	`get_initiator_contact` ()
	`get_requested` ()
	`get_target_contact` ()
	`group_dup_local_pending_contacts` ()
	`group_dup_members_contacts` ()
	`group_dup_remote_pending_contacts` ()
	`group_get_contact_owner` (contact)
	`group_get_flags` ()
	`group_get_handle_owner` (handle)
	`group_get_local_pending` ()
	`group_get_local_pending_contact_info` (local_pending)
	`group_get_local_pending_info` (local_pending)
	`group_get_members` ()
	`group_get_remote_pending` ()
	`group_get_self_contact` ()
	`group_get_self_handle` ()
	`join_async` (message, callback, *user_data)
	`join_finish` (result)
	`leave_async` (reason, message, callback, *user_data)
	`leave_finish` (result)
	`password_needed` ()
	`provide_password_async` (password, callback, *user_data)
	`provide_password_finish` (result)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Inherited:: TelepathyGLib.Proxy (5)

Name	Type	Flags	Short Description
`channel-ready`	`bool`	d/r	Initially `False`; changes to `True` when introspection finishes `deprecated`
`connection`	`TelepathyGLib.Connection`	r/w/co	The connection to which this object belongs.
`group-flags`	`int`	r	0 if not a group
`group-self-contact`	`TelepathyGLib.Contact`	r	Undefined if not a group
`group-self-handle`	`int`	r	Undefined if not a group `deprecated`
`identifier`	`str`	r	The identifier of the channel
`initiator-contact`	`TelepathyGLib.Contact`	r	Undefined if not a group
`initiator-handle`	`int`	r	The handle of the initiator of the channel `deprecated`
`initiator-identifier`	`str`	r	The identifier of the initiator of the channel `deprecated`
`password-needed`	`bool`	r	Password neede to join the channel
`requested`	`bool`	r	`True` if the channel has been requested
`target-contact`	`TelepathyGLib.Contact`	r	The channel’s target contact

Signals¶

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

Name	Short Description
`chat-state-changed`	Emitted when a contact’s chat state changes after `TelepathyGLib.Proxy.prepare_async`() has finished preparing the feature %TP_CHANNEL_FEATURE_CHAT_STATES. `deprecated`
`group-contacts-changed`	Emitted when the group members change in a Group channel.
`group-flags-changed`	Emitted when the `TelepathyGLib.Channel` `:group-flags` property changes while the channel is ready.
`group-members-changed`	Emitted when the group members change in a Group channel that is ready. `deprecated`
`group-members-changed-detailed`	Emitted when the group members change in a Group channel that is ready. `deprecated`

Fields¶

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

Name	Type	Access	Description
parent	`TelepathyGLib.Proxy`	r

Class Details¶

class TelepathyGLib.Channel(**kwargs)¶

Bases:: TelepathyGLib.Proxy
Abstract:: No
Structure:: TelepathyGLib.ChannelClass

A proxy object for a Telepathy channel. A proxy object for a Telepathy channel. There are no interesting public struct fields.

(Changed in 0.7.12: the layout of the structure is visible, allowing subclassing.)

New in version 0.7.1.

classmethod get_feature_quark_chat_states()¶

Return type:: int

classmethod get_feature_quark_contacts()¶

Return type:: int

classmethod get_feature_quark_core()¶

Return type:: int

classmethod get_feature_quark_group()¶

Return type:: int

classmethod get_feature_quark_password()¶

Return type:: int

classmethod init_known_interfaces()¶: Ensure that the known interfaces for TelepathyGLib.Channel have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling tp_proxy_or_subclass_hook_on_interface_add() with first argument %TP_TYPE_CHANNEL.

New in version 0.7.6.

classmethod new(conn, object_path, optional_channel_type, optional_handle_type, optional_handle)¶

Parameters:

conn (TelepathyGLib.Connection) – a connection; may not be None
object_path (str) – the object path of the channel; may not be None
optional_channel_type (str) – the channel type if already known, or None if not
optional_handle_type (TelepathyGLib.HandleType) – the handle type if already known, or TelepathyGLib.UNKNOWN_HANDLE_TYPE if not
optional_handle (int) – the handle if already known, or 0 if not (if optional_handle_type is TelepathyGLib.UNKNOWN_HANDLE_TYPE or TelepathyGLib.HandleType.NONE, this must be 0)

Raises:

GLib.Error

Returns:

a new channel proxy, or None on invalid arguments.

Return type:

TelepathyGLib.Channel

New in version 0.7.1.

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

classmethod new_from_properties(conn, object_path, immutable_properties)¶

Parameters:

conn (TelepathyGLib.Connection) – a 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 new channel proxy, or None on invalid arguments

Return type:

TelepathyGLib.Channel

New in version 0.7.19.

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

borrow_connection()¶

Returns:: the value of TelepathyGLib.Channel :connection
Return type:: TelepathyGLib.Connection

Returns the connection for this channel. The returned pointer is only valid while this channel is valid - reference it with GObject.Object.ref() if needed.

New in version 0.7.12.

Deprecated since version 0.19.9: New code should use TelepathyGLib.Channel.get_connection() instead.

borrow_immutable_properties()¶

Returns:: a GLib.HashTable where the keys are strings, D-Bus interface name + “.” + property name, and the values are GObject.Value instances
Return type:: {str: GObject.Value}

Returns the immutable D-Bus properties of this channel, the same as TelepathyGLib.Channel :channel-properties.

The returned hash table should not be altered, and is not necessarily valid after the main loop is next re-entered. Copy it with GObject.boxed_copy() (its type is %TP_HASH_TYPE_QUALIFIED_PROPERTY_VALUE_MAP) if a copy that remains valid must be kept.

If the TelepathyGLib.Channel :channel-properties property was not set during construction (e.g. by calling TelepathyGLib.Channel.new_from_properties()), a reasonable but possibly incomplete version will be made up from the values of individual properties; reading this property repeatedly may yield progressively more complete values until the %TP_CHANNEL_FEATURE_CORE feature is prepared.

Deprecated since version 0.19.9: New code should use TelepathyGLib.Channel.dup_immutable_properties() instead.

close_async(callback, *user_data)¶

Parameters:

callback (Gio.AsyncReadyCallback or None) – a callback to call when we closed the channel, or None to ignore any reply
user_data (object or None) – data to pass to callback

Close channel self. In most cases, it’s generally cleaner to use TelepathyGLib.Channel.leave_async() instead to properly leave and close the channel.

When the channel has been closed, callback will be called. You can then call TelepathyGLib.Channel.close_finish() to get the result of the operation.

New in version 0.13.10.

close_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.Channel.close_async().
Raises:: GLib.Error
Returns:: True if the channel has been closed; False otherwise
Return type:: bool

Finishes a call to TelepathyGLib.Channel.leave_async().

New in version 0.13.10.

destroy_async(callback, *user_data)¶

Parameters:

callback (Gio.AsyncReadyCallback or None) – a callback to call when we left the channel
user_data (object or None) – data to pass to callback

Destroy channel self. If self doesn’t implement #TP_IFACE_QUARK_CHANNEL_INTERFACE_DESTROYABLE or if for any reason we can’t destroy the channel, we close it.

When the channel has been destroyed or closed, callback will be called. You can then call TelepathyGLib.Channel.destroy_finish() to get the result of the operation.

New in version 0.15.2.

destroy_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.Channel.destroy_async().
Raises:: GLib.Error
Returns:: True if the channel has been destroyed or closed; False otherwise
Return type:: bool

Completes a call to TelepathyGLib.Channel.destroy_async().

New in version 0.15.2.

dup_immutable_properties()¶

Returns:: a dictionary where the keys are strings, D-Bus interface name + “.” + property name.
Return type:: GLib.Variant

Returns the immutable D-Bus properties of this channel, in a variant of type %G_VARIANT_TYPE_VARDICT where the keys are strings, D-Bus interface name + “.” + property name. Use g_variant_lookup() or GLib.Variant.lookup_value() for convenient access to the values.

If the TelepathyGLib.Channel :channel-properties property was not set during construction (e.g. by calling TelepathyGLib.Channel.new_from_properties()), a reasonable but possibly incomplete version will be made up from the values of individual properties; reading this property repeatedly may yield progressively more complete values until the %TP_CHANNEL_FEATURE_CORE feature is prepared.

This function should be used only by TelepathyGLib.Channel subclasses, otherwise it is recommended to use individual property getters instead.

New in version 0.19.9.

get_channel_type()¶

Returns:: the channel type, if the channel is ready; either the channel type or None, if the channel is not yet ready.
Return type:: str

Get the D-Bus interface name representing this channel’s type, if it has been discovered.

This is the same as the #TpChannelIface:channel-type property; it isn’t guaranteed to be non-None until the %TP_CHANNEL_FEATURE_CORE feature has been prepared.

New in version 0.7.12.

get_channel_type_id()¶

Returns:: the channel type, if the channel is ready; either the channel type or 0, if the channel is not yet ready.
Return type:: int

Get the D-Bus interface name representing this channel’s type, as a GQuark, if it has been discovered.

This is the same as the #TpChannelIface:channel-type property, except that it is a GQuark rather than a string. It isn’t guaranteed to be nonzero until the %TP_CHANNEL_FEATURE_CORE property is ready.

New in version 0.7.12.

get_chat_state(contact)¶

Parameters:: contact (int) – a contact handle
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_CHANNEL_FEATURE_CHAT_STATES, the result will always be TelepathyGLib.ChannelChatState.INACTIVE.

New in version 0.11.3.

Deprecated since version ???: Use TelepathyGLib.TextChannel.get_chat_state() instead.

get_connection()¶

Returns:: the value of TelepathyGLib.Channel :connection
Return type:: TelepathyGLib.Connection

Returns the connection for this channel. The returned pointer is only valid while this channel is valid - reference it with GObject.Object.ref() if needed.

New in version 0.19.9.

get_handle()¶

Returns:

the handle

handle_type:: if not None, used to return the type of this handle

Return type:

(int, handle_type: TelepathyGLib.HandleType)

Get the handle representing the contact, chatroom, etc. with which this channel communicates for its whole lifetime, or 0 if there is no such handle or it has not yet been discovered.

This is the same as the #TpChannelIface:handle property. It isn’t guaranteed to have its final value until the %TP_CHANNEL_FEATURE_CORE feature is ready.

If handle_type is not None, the type of handle is written into it. This will be TelepathyGLib.UNKNOWN_HANDLE_TYPE if the handle has not yet been discovered, or TelepathyGLib.HandleType.NONE if there is no handle with which this channel will always communicate. This is the same as the #TpChannelIface:handle-type property.

New in version 0.7.12.

get_identifier()¶

Returns:: the identifier
Return type:: str

This channel’s associated identifier, or the empty string if no identifier or unknown.

This is the same as the TelepathyGLib.Channel :identifier property, and isn’t guaranteed to be set until the %TP_CHANNEL_FEATURE_CORE property is ready.

Changed in 0.11.4: as with TelepathyGLib.Channel :identifier, this could previously either be None or the empty string if there was no suitable value. It is now non-None in all cases.

New in version 0.7.21.

get_initiator_contact()¶

Returns:: the value of TelepathyGLib.Channel :initiator-contact
Return type:: TelepathyGLib.Contact

New in version 0.15.6.

get_requested()¶

Returns:: the value of TelepathyGLib.Channel :requested
Return type:: bool

Return the TelepathyGLib.Channel :requested property

New in version 0.11.15.

get_target_contact()¶

Returns:: the value of TelepathyGLib.Channel :target-contact
Return type:: TelepathyGLib.Contact

New in version 0.15.6.

group_dup_local_pending_contacts()¶

Returns:: a new GLib.PtrArray of TelepathyGLib.Contact, free it with g_ptr_array_unref(), or None.
Return type:: [TelepathyGLib.Contact]

If self is a group and the %TP_CHANNEL_FEATURE_CONTACTS feature has been prepared, return a GLib.PtrArray containing its local-pending members.

If self is a group but %TP_CHANNEL_FEATURE_CONTACTS has not been prepared, the result may either be a set of local-pending members, or None.

If self is not a group, return None.

New in version 0.15.6.

group_dup_members_contacts()¶

Returns:: a new GLib.PtrArray of TelepathyGLib.Contact, free it with g_ptr_array_unref(), or None.
Return type:: [TelepathyGLib.Contact]

If self is a group and the %TP_CHANNEL_FEATURE_CONTACTS feature has been prepared, return a GLib.PtrArray containing its members.

If self is a group but %TP_CHANNEL_FEATURE_CONTACTS has not been prepared, the result may either be a set of members, or None.

If self is not a group, return None.

New in version 0.15.6.

group_dup_remote_pending_contacts()¶

Returns:: a new GLib.PtrArray of TelepathyGLib.Contact, free it with g_ptr_array_unref(), or None.
Return type:: [TelepathyGLib.Contact]

If self is a group and the %TP_CHANNEL_FEATURE_CONTACTS feature has been prepared, return a GLib.PtrArray containing its remote-pending members.

If self is a group but %TP_CHANNEL_FEATURE_CONTACTS has not been prepared, the result may either be a set of remote-pending members, or None.

If self is not a group, return None.

New in version 0.15.6.

group_get_contact_owner(contact)¶

Parameters:: contact (TelepathyGLib.Contact) – a contact which is a member of this channel
Returns:: the global contact that owns the given contact, or None.
Return type:: TelepathyGLib.Contact

Synopsis (see below for further explanation):

if self is not a group or contact is not a member of this channel, result is undefined;
if %TP_CHANNEL_FEATURE_CONTACTS has not yet been prepared, result is undefined;
if self does not have flags that include TelepathyGLib.ChannelGroupFlags.PROPERTIES, result is undefined;
if contact is channel-specific and its globally valid “owner” is known, return that owner;
if contact is channel-specific and its globally valid “owner” is unknown, return None;
if contact is globally valid, return contact itself

Some channels (those with flags that include TelepathyGLib.ChannelGroupFlags.CHANNEL_SPECIFIC_HANDLES) have a concept of “channel-specific contacts”. These are contacts that only have meaning within the context of the channel - for instance, in XMPP Multi-User Chat, participants in a chatroom are identified by an in-room JID consisting of the JID of the chatroom plus a local nickname.

Depending on the protocol and configuration, it might be possible to find out what globally valid contact (i.e. a contact that you could add to your contact list) “owns” a channel-specific contact. For instance, in most XMPP MUC chatrooms, normal users cannot see what global JID corresponds to an in-room JID, but moderators can.

This is further complicated by the fact that channels with channel-specific contacts can sometimes have members with globally valid contacts (for instance, if you invite someone to an XMPP MUC using their globally valid JID, you would expect to see the contact representing that JID in the Group’s remote-pending set).

New in version 0.15.6.

group_get_flags()¶

Returns:: the group flags, or 0
Return type:: TelepathyGLib.ChannelGroupFlags

Return the TelepathyGLib.Channel :group-flags property (see the description of that property for notes on validity).

New in version 0.7.12.

group_get_handle_owner(handle)¶

Parameters:: handle (int) – a handle which is a member of this channel
Returns:: the global handle that owns the given handle, or 0
Return type:: int

Synopsis (see below for further explanation):

if self is not a group or handle is not a member of this channel, result is undefined;
if %TP_CHANNEL_FEATURE_GROUP has not yet been prepared, result is undefined;
if self does not have flags that include TelepathyGLib.ChannelGroupFlags.PROPERTIES, result is undefined;
if handle is channel-specific and its globally valid “owner” is known, return that owner;
if handle is channel-specific and its globally valid “owner” is unknown, return zero;
if handle is globally valid, return handle itself

Some channels (those with flags that include TelepathyGLib.ChannelGroupFlags.CHANNEL_SPECIFIC_HANDLES) have a concept of “channel-specific handles”. These are handles that only have meaning within the context of the channel - for instance, in XMPP Multi-User Chat, participants in a chatroom are identified by an in-room JID consisting of the JID of the chatroom plus a local nickname.

Depending on the protocol and configuration, it might be possible to find out what globally valid handle (i.e. an identifier that you could add to your contact list) “owns” a channel-specific handle. For instance, in most XMPP MUC chatrooms, normal users cannot see what global JID corresponds to an in-room JID, but moderators can.

This is further complicated by the fact that channels with channel-specific handles can sometimes have members with globally valid handles (for instance, if you invite someone to an XMPP MUC using their globally valid JID, you would expect to see the handle representing that JID in the Group’s remote-pending set).

This function’s result is undefined unless the channel is ready and its flags include TelepathyGLib.ChannelGroupFlags.PROPERTIES (an implementation without extra D-Bus round trips is not possible using the older API).

New in version 0.7.12.

Deprecated since version ???: New code should use TelepathyGLib.Channel.group_get_contact_owner() instead.

group_get_local_pending()¶

Returns:: the local-pending members, or None
Return type:: TelepathyGLib.Intset

If self is a group and the %TP_CHANNEL_FEATURE_GROUP feature has been prepared, return a TelepathyGLib.Intset containing its local-pending members.

If self is a group but %TP_CHANNEL_FEATURE_GROUP has not been prepared, the result may either be a set of local-pending members, or None.

If self is not a group, return None.

New in version 0.7.12.

Deprecated since version ???: New code should use TelepathyGLib.Channel.group_dup_local_pending_contacts() instead.

group_get_local_pending_contact_info(local_pending)¶

Parameters:

local_pending (TelepathyGLib.Contact) – the TelepathyGLib.Contact of a local-pending contact about whom more information is needed

Returns:

True if the contact is in fact local-pending

actor:: either None or a location to return the contact who requested the change
reason:: either None or a location to return the reason for the change
message:: either None or a location to return the user-supplied message

Return type:

(bool, actor: TelepathyGLib.Contact, reason: TelepathyGLib.ChannelGroupChangeReason, message: str)

If local_pending is actually a local-pending contact, write additional information into actor, reason and message and return True. The contact and message are not referenced or copied, and can only be assumed to remain valid until the main loop is re-entered.

If local_pending is not the handle of a local-pending contact, write None into actor, TelepathyGLib.ChannelGroupChangeReason.NONE into reason and “” into message, and return False.

New in version 0.15.6.

group_get_local_pending_info(local_pending)¶

Parameters:

local_pending (int) – the handle of a local-pending contact about whom more information is needed

Returns:

True if the contact is in fact local-pending

actor:: either None or a location to return the contact who requested the change
reason:: either None or a location to return the reason for the change
message:: either None or a location to return the user-supplied message

Return type:

(bool, actor: int, reason: TelepathyGLib.ChannelGroupChangeReason, message: str)

If local_pending is actually the handle of a local-pending contact, write additional information into actor, reason and message and return True. The handle and message are not referenced or copied, and can only be assumed to remain valid until the main loop is re-entered.

If local_pending is not the handle of a local-pending contact, write 0 into actor, TelepathyGLib.ChannelGroupChangeReason.NONE into reason and “” into message, and return False.

New in version 0.7.12.

Deprecated since version ???: New code should use TelepathyGLib.Channel.group_get_local_pending_contact_info() instead.

group_get_members()¶

Returns:: the members, or None
Return type:: TelepathyGLib.Intset

If self is a group and the %TP_CHANNEL_FEATURE_GROUP feature has been prepared, return a TelepathyGLib.Intset containing its members.

If self is a group but %TP_CHANNEL_FEATURE_GROUP has not been prepared, the result may either be a set of members, or None.

If self is not a group, return None.

New in version 0.7.12.

Deprecated since version ???: New code should use TelepathyGLib.Channel.group_dup_members_contacts() instead.

group_get_remote_pending()¶

Returns:: the remote-pending members, or None
Return type:: TelepathyGLib.Intset

If self is a group and the %TP_CHANNEL_FEATURE_GROUP feature has been prepared, return a TelepathyGLib.Intset containing its remote-pending members.

If self is a group but %TP_CHANNEL_FEATURE_GROUP has not been prepared, the result may either be a set of remote-pending members, or None.

If self is not a group, return None.

New in version 0.7.12.

Deprecated since version ???: New code should use TelepathyGLib.Channel.group_dup_remote_pending_contacts() instead.

group_get_self_contact()¶

Returns:: the value of TelepathyGLib.Channel :group-self-contact
Return type:: TelepathyGLib.Contact

New in version 0.15.6.

group_get_self_handle()¶

Returns:: the handle representing the user, or 0
Return type:: int

Return the TelepathyGLib.Channel :group-self-handle property (see the description of that property for notes on validity).

New in version 0.7.12.

Deprecated since version ???: New code should use TelepathyGLib.Channel.group_get_self_contact() instead.

join_async(message, callback, *user_data)¶

Parameters:

message (str) – the join message
callback (Gio.AsyncReadyCallback or None) – a callback to call when we joined the channel
user_data (object or None) – data to pass to callback

Join channel self with message as join message.

When we joined the channel, callback will be called. You can then call TelepathyGLib.Channel.join_finish() to get the result of the operation.

Note that unlike TelepathyGLib.Channel.leave_async(), %TP_CHANNEL_FEATURE_GROUP feature must be prepared before calling this function.

New in version 0.15.5.

join_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.Channel.join_async().
Raises:: GLib.Error
Returns:: True if the channel was successfully joined; False otherwise
Return type:: bool

Completes a call to TelepathyGLib.Channel.join_async().

New in version 0.15.5.

leave_async(reason, message, callback, *user_data)¶

Parameters:

reason (TelepathyGLib.ChannelGroupChangeReason) – the leave reason
message (str) – the leave message
callback (Gio.AsyncReadyCallback or None) – a callback to call when we left the channel
user_data (object or None) – data to pass to callback

Leave channel self with reason as reason and message as leave message. If self doesn’t implement #TP_IFACE_QUARK_CHANNEL_INTERFACE_GROUP or if for any reason we can’t properly leave the channel, we close it.

When we left the channel, callback will be called. You can then call TelepathyGLib.Channel.leave_finish() to get the result of the operation.

Note that unlike TelepathyGLib.Channel.join_async(), %TP_CHANNEL_FEATURE_GROUP feature does not have to be prepared and will be prepared for you. But this is a deprecated behaviour.

New in version 0.13.10.

leave_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.Channel.leave_async().
Raises:: GLib.Error
Returns:: True if the channel has been left; False otherwise
Return type:: bool

Completes a call to TelepathyGLib.Channel.leave_async().

New in version 0.13.10.

password_needed()¶

Returns:: the value of TelepathyGLib.Channel :password-needed
Return type:: bool

Return the TelepathyGLib.Channel :password-needed property

New in version 0.15.2.

provide_password_async(password, callback, *user_data)¶

Parameters:

password (str) – the password
callback (Gio.AsyncReadyCallback or None) – a callback to call when password has been provided
user_data (object or None) – data to pass to callback

Provide password so that self can be joined. This function must be called with the correct password in order for channel joining to proceed if the TelepathyGLib.Channel :password-needed property is set.

Once the password has been provided, callback will be called. You can then call TelepathyGLib.Channel.provide_password_finish() to get the result of the operation.

New in version 0.15.2.

provide_password_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult passed to the callback for TelepathyGLib.Channel.provide_password_async().
Raises:: GLib.Error
Returns:: True if the password has been provided and accepted, False otherwise.
Return type:: bool

Completes a call to TelepathyGLib.Channel.provide_password_async(). If the password was rejected, the operation fails with TelepathyGLib.Error.AUTHENTICATION_FAILED.

New in version 0.15.2.

Signal Details¶

TelepathyGLib.Channel.signals.chat_state_changed(channel, contact, state)¶

Signal Name:

chat-state-changed

Flags:

RUN_LAST, DETAILED

Parameters:

channel (TelepathyGLib.Channel) – The object which received the signal
contact (int) – a contact handle 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 the feature %TP_CHANNEL_FEATURE_CHAT_STATES.

New in version 0.11.3.

Deprecated since version ???: Use TelepathyGLib.TextChannel ::contact-chat-state-changed instead

TelepathyGLib.Channel.signals.group_contacts_changed(channel, added, removed, local_pending, remote_pending, actor, details)¶

Signal Name:

group-contacts-changed

Flags:

RUN_LAST, DETAILED

Parameters:

channel (TelepathyGLib.Channel) – The object which received the signal
added ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact containing the full members added
removed ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact containing the members (full, local-pending or remote-pending) removed
local_pending ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact containing the local-pending members added
remote_pending ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact containing the remote-pending members added
actor (TelepathyGLib.Contact) – a TelepathyGLib.Contact for the “actor” handle in details
details ({str: GObject.Value}) – a GLib.HashTable mapping (str *) to GObject.Value containing details about the change, as described in the specification of the MembersChangedDetailed signal.

Emitted when the group members change in a Group channel.

This is not guaranteed to be emitted until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CONTACTS; until then, it may be omitted.

New in version 0.15.6.

TelepathyGLib.Channel.signals.group_flags_changed(channel, added, removed)¶

Signal Name:

group-flags-changed

Flags:

RUN_LAST, DETAILED

Parameters:

channel (TelepathyGLib.Channel) – The object which received the signal
added (int) – TelepathyGLib.ChannelGroupFlags which are newly set
removed (int) – TelepathyGLib.ChannelGroupFlags which are no longer set

Emitted when the TelepathyGLib.Channel :group-flags property changes while the channel is ready.

New in version 0.7.12.

TelepathyGLib.Channel.signals.group_members_changed()¶

Signal Name:: group-members-changed
Flags:: RUN_LAST, DETAILED

Emitted when the group members change in a Group channel that is ready.

New in version 0.7.12.

Deprecated since version ???: Use TelepathyGLib.Channel ::group-contacts-changed instead.

TelepathyGLib.Channel.signals.group_members_changed_detailed(channel, added, removed, local_pending, remote_pending, details)¶

Signal Name:

group-members-changed-detailed

Flags:

RUN_LAST, DETAILED

Parameters:

channel (TelepathyGLib.Channel) – The object which received the signal
added ([int]) – a GLib.Array of int containing the full members added
removed ([int]) – a GLib.Array of int containing the members (full, local-pending or remote-pending) removed
local_pending ([int]) – a GLib.Array of int containing the local-pending members added
remote_pending ([int]) – a GLib.Array of int containing the remote-pending members added
details ({str: GObject.Value}) – a GLib.HashTable mapping (str *) to GObject.Value containing details about the change, as described in the specification of the MembersChangedDetailed signal.

Emitted when the group members change in a Group channel that is ready. Contains a superset of the information in the TelepathyGLib.Channel ::group-members-changed signal, and is emitted at the same time; applications can connect to this signal and ignore the other.

New in version 0.7.21.

Deprecated since version ???: Use TelepathyGLib.Channel ::group-contacts-changed instead.

Property Details¶

TelepathyGLib.Channel.props.channel_ready¶

Name:: channel-ready
Type:: bool
Default Value:: False
Flags:: DEPRECATED, READABLE

Initially False; changes to True when TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CORE, and if the channel is a group, %TP_CHANNEL_FEATURE_GROUP.

This is a less general form of TelepathyGLib.Proxy.is_prepared(), which should be used in new code.

One important difference is that after TelepathyGLib.Proxy ::invalidated is signalled, TelepathyGLib.Channel :channel-ready keeps its current value - which might be True, if the channel was successfully prepared before it became invalidated - but TelepathyGLib.Proxy.is_prepared() returns False for all features.

Change notification is via notify::channel-ready.

Deprecated since version 0.17.6: use TelepathyGLib.Proxy.is_prepared() with %TP_CHANNEL_FEATURE_CORE for checks, or TelepathyGLib.Proxy.prepare_async() for notification

TelepathyGLib.Channel.props.connection¶

Name:: connection
Type:: TelepathyGLib.Connection
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The TelepathyGLib.Connection to which this TelepathyGLib.Channel belongs. Used for e.g. handle manipulation.

TelepathyGLib.Channel.props.group_flags¶

Name:: group-flags
Type:: int
Default Value:: 0
Flags:: READABLE

If the %TP_CHANNEL_FEATURE_GROUP feature has been prepared successfully, TelepathyGLib.ChannelGroupFlags indicating the capabilities and behaviour of that group.

Otherwise, this may be 0.

Change notification is via notify::group-flags or TelepathyGLib.Channel ::group-flags-changed.

New in version 0.7.12.

TelepathyGLib.Channel.props.group_self_contact¶

Name:: group-self-contact
Type:: TelepathyGLib.Contact
Default Value:: None
Flags:: READABLE

If this channel is a group and %TP_CHANNEL_FEATURE_CONTACTS has been prepared, and the user is a member of the group, the TelepathyGLib.Contact representing them in this group.

Otherwise, the result may be either a contact representing the user, or None.

Change notification is via notify::group-self-contact.

New in version 0.15.6.

TelepathyGLib.Channel.props.group_self_handle¶

Name:: group-self-handle
Type:: int
Default Value:: 0
Flags:: READABLE

If this channel is a group and %TP_CHANNEL_FEATURE_GROUP has been prepared, and the user is a member of the group, the #TpHandle representing them in this group.

Otherwise, the result may be either a handle representing the user, or 0.

Change notification is via notify::group-self-handle.

New in version 0.7.12.

Deprecated since version ???: Use TelepathyGLib.Channel :group-self-contact instead.

TelepathyGLib.Channel.props.identifier¶

Name:: identifier
Type:: str
Default Value:: ''
Flags:: READABLE

This channel’s associated identifier, or the empty string if it has handle type TelepathyGLib.HandleType.NONE.

For channels where #TpChannelIface:handle is non-zero, this is the result of inspecting #TpChannelIface:handle.

This is not guaranteed to be set until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CORE; until then, it may be the empty string.

Changed in 0.11.4: this property is never None. Previously, it was None before an identifier was known, or when a channel with no TargetID D-Bus property had TargetHandleType TelepathyGLib.HandleType.NONE.

TelepathyGLib.Channel.props.initiator_contact¶

Name:: initiator-contact
Type:: TelepathyGLib.Contact
Default Value:: None
Flags:: READABLE

The TelepathyGLib.Contact of the initiator of this channel, or None if there is no particular initiator.

If the channel was initiated by a remote contact, this represents that contact, and TelepathyGLib.Channel :requested will be False. For instance, for an incoming call this property indicates the caller, and for a chatroom invitation this property indicates who sent the invitation.

If the channel was requested by the local user, TelepathyGLib.Channel :requested will be True, and this property may be the TelepathyGLib.Channel :group-self-contact or TelepathyGLib.Connection :self-contact.

If the channel appeared for some other reason (for instance as a side-effect of connecting to the server), this property may be None.

This is not guaranteed to be set until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CONTACTS; until then, it may be None.

New in version 0.15.6.

TelepathyGLib.Channel.props.initiator_handle¶

Name:: initiator-handle
Type:: int
Default Value:: 0
Flags:: READABLE

The TelepathyGLib.HandleType.CONTACT #TpHandle of the initiator of this channel, or 0 if there is no particular initiator.

If the channel was initiated by a remote contact, this handle represents that contact, and TelepathyGLib.Channel :requested will be False. For instance, for an incoming call this property indicates the caller, and for a chatroom invitation this property indicates who sent the invitation.

If the channel was requested by the local user, TelepathyGLib.Channel :requested will be True, and this property may be the TelepathyGLib.Channel :group-self-handle or TelepathyGLib.Connection :self-handle.

If the channel appeared for some other reason (for instance as a side-effect of connecting to the server), this property may be 0.

This is not guaranteed to be set until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CORE; until then, it may be 0.

New in version 0.11.15.

Deprecated since version ???: Use TelepathyGLib.Channel :initiator-contact instead.

TelepathyGLib.Channel.props.initiator_identifier¶

Name:: initiator-identifier
Type:: str
Default Value:: ''
Flags:: READABLE

If TelepathyGLib.Channel :initiator-handle is 0, this will always be “”. Otherwise, this will be the TelepathyGLib.Contact :identifier of the contact with that handle.

This is not guaranteed to be set until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CORE; until then, it may be the empty string.

New in version 0.11.15.

Deprecated since version ???: Use TelepathyGLib.Channel :initiator-contact instead.

TelepathyGLib.Channel.props.password_needed¶

Name:: password-needed
Type:: bool
Default Value:: False
Flags:: READABLE

If True, TelepathyGLib.Channel.provide_password_async() has to be called to be able to join the channel.

This is not guaranteed to be meaningful until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_PASSWORD; until then, it may return False even if the channel is actually protected by a password. Preparing %TP_CHANNEL_FEATURE_PASSWORD also ensures that the notify::password-needed signal will be fired when this property changes.

New in version 0.15.2.

TelepathyGLib.Channel.props.requested¶

Name:: requested
Type:: bool
Default Value:: False
Flags:: READABLE

True if this channel was created in response to a local request, such as a call to TelepathyGLib.AccountChannelRequest.create_channel_async(). False if this channel was initiated by a remote contact (the TelepathyGLib.Channel :initiator-handle), or if it appeared as a side-effect of some other action.

For instance, this is False on incoming calls and file transfers, remotely-initiated 1-1 text conversations, and invitations to chatrooms, and True on outgoing calls and file transfers, locally-initiated 1-1 text conversations, and chatrooms joined by local user action.

This is not guaranteed to be meaningful until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CORE; until then, it may return False even if the channel was actually requested.

New in version 0.11.15.

TelepathyGLib.Channel.props.target_contact¶

Name:: target-contact
Type:: TelepathyGLib.Contact
Default Value:: None
Flags:: READABLE

If this channel is for communication with a single contact (that is, #TpChannelIface:handle-type is TelepathyGLib.HandleType.CONTACT), then a TelepathyGLib.Contact representing the remote contact. For chat rooms, contact search channels and other channels without a single remote contact, None.

This is not guaranteed to be set until TelepathyGLib.Proxy.prepare_async() has finished preparing %TP_CHANNEL_FEATURE_CONTACTS; until then, it may be None.

New in version 0.15.6.