TelepathyGLib.Channel

g GObject.Object GObject.Object TelepathyGLib.Proxy TelepathyGLib.Proxy GObject.Object->TelepathyGLib.Proxy TelepathyGLib.Channel TelepathyGLib.Channel TelepathyGLib.Proxy->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:

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:

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:

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:

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:

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:

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:

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:

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:

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.