TelepathyGLib.Protocol¶

Subclasses:: None

Methods¶

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

class	`get_feature_quark_core` ()
class	`get_feature_quark_parameters` ()
class	`init_known_interfaces` ()
class	`new` (dbus, cm_name, protocol_name, immutable_properties)
class	`new_vardict` (dbus, cm_name, protocol_name, immutable_properties)
	`can_register` ()
	`dup_immutable_properties` ()
	`dup_param` (param)
	`dup_param_names` ()
	`dup_params` ()
	`dup_presence_statuses` ()
	`get_addressable_uri_schemes` ()
	`get_addressable_vcard_fields` ()
	`get_authentication_types` ()
	`get_avatar_requirements` ()
	`get_capabilities` ()
	`get_cm_name` ()
	`get_english_name` ()
	`get_icon_name` ()
	`get_name` ()
	`get_param` (param)
	`get_vcard_field` ()
	`has_param` (param)
	`identify_account_async` (vardict, cancellable, callback, *user_data)
	`identify_account_finish` (result)
	`normalize_contact_async` (contact, cancellable, callback, *user_data)
	`normalize_contact_finish` (result)
	`normalize_contact_uri_async` (uri, cancellable, callback, *user_data)
	`normalize_contact_uri_finish` (result)
	`normalize_vcard_address_async` (field, value, cancellable, callback, *user_data)
	`normalize_vcard_address_finish` (result)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Inherited:: TelepathyGLib.Proxy (5)

Name	Type	Flags	Short Description
`addressable-uri-schemes`	[`str`]	r	A list of URI schemes
`addressable-vcard-fields`	[`str`]	r	A list of vCard fields
`authentication-types`	[`str`]	r	A list of authentication types
`avatar-requirements`	`int`	r	Avatars requirements
`capabilities`	`TelepathyGLib.Capabilities`	r	Requestable channel classes for this Protocol
`cm-name`	`str`	r/w/co	Name of the CM this protocol is on
`english-name`	`str`	r	A non-`None` English name for this Protocol
`icon-name`	`str`	r	A non-`None` Icon name for this Protocol
`param-names`	[`str`]	r	A list of parameter names
`protocol-name`	`str`	r/w/co	The Protocol from telepathy-spec, such as ‘jabber’ or ‘local-xmpp’
`protocol-properties-vardict`	`GLib.Variant`	r	The immutable properties of this Protocol
`vcard-field`	`str`	r	A lower-case vCard name for this Protocol, or `None`

Signals¶

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

Fields¶

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

Name	Type	Access	Description
parent	`TelepathyGLib.Proxy`	r

Class Details¶

class TelepathyGLib.Protocol(**kwargs)¶

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

A base class for connection managers’ protocols.

New in version 0.11.11.

classmethod get_feature_quark_core()¶

Return type:: int

classmethod get_feature_quark_parameters()¶

Return type:: int

classmethod init_known_interfaces()¶: Ensure that the known interfaces for TelepathyGLib.Protocol 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_PROTOCOL.

New in version 0.11.11.

classmethod new(dbus, cm_name, protocol_name, immutable_properties)¶

Parameters:

dbus (TelepathyGLib.DBusDaemon) – proxy for the D-Bus daemon; may not be None
cm_name (str) – the connection manager name (such as “gabble”)
protocol_name (str) – the protocol name (such as “jabber”)
immutable_properties ({object: object}) – the immutable D-Bus properties for this protocol

Raises:

GLib.Error

Returns:

a new protocol proxy, or None on invalid arguments

Return type:

TelepathyGLib.Protocol

New in version 0.11.11.

classmethod new_vardict(dbus, cm_name, protocol_name, immutable_properties)¶

Parameters:

dbus (TelepathyGLib.DBusDaemon) – proxy for the D-Bus daemon; may not be None
cm_name (str) – the connection manager name (such as “gabble”)
protocol_name (str) – the protocol name (such as “jabber”)
immutable_properties (GLib.Variant) – the immutable D-Bus properties for this protocol

Raises:

GLib.Error

Returns:

a new protocol proxy, or None on invalid arguments

Return type:

TelepathyGLib.Protocol

Create a new protocol proxy.

If immutable_properties is a floating reference, this function will take ownership of it, much like GLib.Variant.ref_sink(). See documentation of that function for details.

New in version 0.23.3.

can_register()¶

Returns:: True if protocol supports the parameter “register”
Return type:: bool

Return whether a new account can be registered on this protocol, by setting the special “register” parameter to True.

New in version 0.11.11.

dup_immutable_properties()¶

Returns:: the value of TelepathyGLib.Protocol :protocol-properties-vardict
Return type:: GLib.Variant

Return the TelepathyGLib.Protocol :protocol-properties-vardict property.

New in version 0.23.3.

dup_param(param)¶

Parameters:: param (str) – a parameter name
Returns:: a structure representing the parameter param, or None if not supported. Free with TelepathyGLib.ConnectionManagerParam.free()
Return type:: TelepathyGLib.ConnectionManagerParam

no more to say

New in version 0.17.6.

dup_param_names()¶

Returns:: a copy of TelepathyGLib.Protocol :param-names
Return type:: [str]

Returns a list of parameter names supported by this connection manager for this protocol.

The result is copied and must be freed by the caller with GLib.strfreev().

New in version 0.11.11.

dup_params()¶

Returns:: a list of TelepathyGLib.ConnectionManagerParam structures, owned by the caller
Return type:: [TelepathyGLib.ConnectionManagerParam]

Returns a list of parameters supported by this connection manager.

The returned list must be freed by the caller, for instance with g_list_free_full (l, (GDestroyNotify) tp_connection_manager_param_free).

New in version 0.17.6.

dup_presence_statuses()¶

Returns:: a list of statuses, or None if unknown
Return type:: [TelepathyGLib.PresenceStatusSpec]

Return the presence statuses that might be supported by connections to this protocol.

It is possible that some of these statuses will not actually be supported by a connection: for instance, an XMPP connection manager would include “hidden” in this list, even though not all XMPP servers allow users to be online-but-hidden.

get_addressable_uri_schemes()¶

Returns:: the value of TelepathyGLib.Protocol :addressable-uri-schemes
Return type:: [str]

New in version 0.23.1.

get_addressable_vcard_fields()¶

Returns:: the value of TelepathyGLib.Protocol :addressable-vcard-fields
Return type:: [str]

New in version 0.23.1.

get_authentication_types()¶

Returns:: the value of TelepathyGLib.Protocol :authentication-types
Return type:: [str]

New in version 0.13.9.

get_avatar_requirements()¶

Returns:: the value of TelepathyGLib.Protocol :avatar-requirements
Return type:: TelepathyGLib.AvatarRequirements

Return the TelepathyGLib.Protocol :avatar-requirements property

New in version 0.15.6.

get_capabilities()¶

Returns:: TelepathyGLib.Protocol :capabilities, which must be referenced (if non-None) if it will be kept
Return type:: TelepathyGLib.Capabilities

New in version 0.11.11.

get_cm_name()¶

Returns:: the value of TelepathyGLib.Protocol :cm-name
Return type:: str

Return the TelepathyGLib.Protocol :cm-name property.

New in version 0.19.1.

get_english_name()¶

Returns:: the non-None, non-empty value of TelepathyGLib.Protocol :english-name
Return type:: str

New in version 0.11.11.

get_icon_name()¶

Returns:: the non-None, non-empty value of TelepathyGLib.Protocol :icon-name
Return type:: str

New in version 0.11.11.

get_name()¶

Returns:: the value of the TelepathyGLib.Protocol :protocol-name property
Return type:: str

Return the same thing as the protocol-name property, for convenient use in C code. The returned string is valid for as long as self exists.

New in version 0.11.11.

get_param(param)¶

Parameters:: param (str) – a parameter name
Returns:: a structure representing the parameter param, or None if not supported
Return type:: TelepathyGLib.ConnectionManagerParam

no more to say

New in version 0.11.11.

get_vcard_field()¶

Returns:: the value of TelepathyGLib.Protocol :vcard-field
Return type:: str

New in version 0.11.11.

has_param(param)¶

Parameters:: param (str) – a parameter name
Returns:: True if self supports the parameter param.
Return type:: bool

no more to say

New in version 0.11.11.

identify_account_async(vardict, cancellable, callback, *user_data)¶

Parameters:

vardict (GLib.Variant) – the account parameters as a GLib.Variant of type %G_VARIANT_TYPE_VARDICT. If it is floating, ownership will be taken, as if via GLib.Variant.ref_sink().
cancellable (Gio.Cancellable or None) – may be used to cancel the async request
callback (Gio.AsyncReadyCallback or None) – a callback to call when the request is satisfied
user_data (object or None) – data to pass to callback

Return a string that could identify the account with the given parameters. In most protocols that string is a normalized ‘account’ parameter, but some protocols have more complex requirements; for instance, on IRC, the ‘account’ (nickname) is insufficient, and must be combined with a server or network name.

New in version 0.23.1.

identify_account_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: a string identifying the account, or None on error
Return type:: str

Interpret the result of TelepathyGLib.Protocol.identify_account_async().

New in version 0.23.1.

normalize_contact_async(contact, cancellable, callback, *user_data)¶

Parameters:

contact (str) – a contact identifier, possibly invalid
cancellable (Gio.Cancellable or None) – may be used to cancel the async request
callback (Gio.AsyncReadyCallback or None) – a callback to call when the request is satisfied
user_data (object or None) – data to pass to callback

Perform best-effort offline contact normalization. This does syntactic normalization (e.g. transforming case-insensitive text to lower-case), but does not query servers or anything similar.

New in version 0.23.1.

normalize_contact_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: the normalized form of contact, or None on error
Return type:: str

Interpret the result of TelepathyGLib.Protocol.normalize_contact_async().

New in version 0.23.1.

normalize_contact_uri_async(uri, cancellable, callback, *user_data)¶

Parameters:

uri (str) – a contact URI, possibly invalid
cancellable (Gio.Cancellable or None) – may be used to cancel the async request
callback (Gio.AsyncReadyCallback or None) – a callback to call when the request is satisfied
user_data (object or None) – data to pass to callback

Perform best-effort offline contact normalization, for a contact in the form of a URI. This method will fail if the URI is not in a scheme supported by this protocol or connection manager.

New in version 0.23.1.

normalize_contact_uri_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: the normalized form of uri, or None on error
Return type:: str

Interpret the result of TelepathyGLib.Protocol.normalize_contact_uri_async().

New in version 0.23.1.

normalize_vcard_address_async(field, value, cancellable, callback, *user_data)¶

Parameters:

field (str) – a vCard field
value (str) – an address that is a value of field
cancellable (Gio.Cancellable or None) – may be used to cancel the async request
callback (Gio.AsyncReadyCallback or None) – a callback to call when the request is satisfied
user_data (object or None) – data to pass to callback

Perform best-effort offline contact normalization, for a contact in the form of a vCard field. This method will fail if the vCard field is not supported by this protocol or connection manager.

New in version 0.23.1.

normalize_vcard_address_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: the normalized form of value, or None on error
Return type:: str

Interpret the result of TelepathyGLib.Protocol.normalize_vcard_address_async().

New in version 0.23.1.

Property Details¶

TelepathyGLib.Protocol.props.addressable_uri_schemes¶

Name:: addressable-uri-schemes
Type:: [str]
Default Value:: []
Flags:: READABLE

A non-None #GStrv of URI schemes supported by this protocol. If this protocol does not support addressing contacts by URI, the list is empty.

For instance, a SIP connection manager that supports calling contacts by SIP URI (sip:alice&commat;example.com, sips:bob&commat;example.com) or telephone number (tel:+1-555-0123) might have { “sip”, “sips”, “tel”, None }.

New in version 0.23.1.

TelepathyGLib.Protocol.props.addressable_vcard_fields¶

Name:: addressable-vcard-fields
Type:: [str]
Default Value:: []
Flags:: READABLE

A non-None #GStrv of vCard fields supported by this protocol. If this protocol does not support addressing contacts by a vCard field, the list is empty.

For instance, a SIP connection manager that supports calling contacts by SIP URI (vCard field SIP) or telephone number (vCard field TEL) might have { “sip”, “tel”, None }.

New in version 0.23.1.

TelepathyGLib.Protocol.props.authentication_types¶

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

A non-None #GStrv of interfaces which provide information as to what kind of authentication channels can possibly appear before the connection reaches the CONNECTED state, or None if %TP_PROTOCOL_FEATURE_CORE has not been prepared.

New in version 0.13.9.

TelepathyGLib.Protocol.props.avatar_requirements¶

Name:: avatar-requirements
Type:: int
Default Value:: None
Flags:: READABLE

A TelepathyGLib.AvatarRequirements representing the avatar requirements on this protocol, or None if %TP_PROTOCOL_FEATURE_CORE has not been prepared or if the protocol doesn’t support avatars.

New in version 0.15.6.

TelepathyGLib.Protocol.props.capabilities¶

Name:: capabilities
Type:: TelepathyGLib.Capabilities
Default Value:: None
Flags:: READABLE

The classes of channel that can be requested from connections to this protocol, or None if this is unknown or the %TP_PROTOCOL_FEATURE_CORE feature has not been prepared.

New in version 0.11.11.

TelepathyGLib.Protocol.props.cm_name¶

Name:: cm-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The name of the connection manager this protocol is on.

New in version 0.19.1.

TelepathyGLib.Protocol.props.english_name¶

Name:: english-name
Type:: str
Default Value:: None
Flags:: READABLE

The name of the protocol in a form suitable for display to users, such as “AIM” or “Yahoo!”, or a string based on TelepathyGLib.Protocol :protocol-name (currently constructed by putting the first character in title case, but this is not guaranteed) if no better name is available or the %TP_PROTOCOL_FEATURE_CORE feature has not been prepared.

This is effectively in the C locale (international English); user interfaces requiring a localized protocol name should look one up in their own message catalog based on either TelepathyGLib.Protocol :protocol-name or TelepathyGLib.Protocol :english-name, but should use this English version as a fallback if no translated version can be found.

New in version 0.11.11.

TelepathyGLib.Protocol.props.icon_name¶

Name:: icon-name
Type:: str
Default Value:: None
Flags:: READABLE

The name of an icon in the system’s icon theme. If none was supplied by the Protocol, or the %TP_PROTOCOL_FEATURE_CORE feature has not been prepared, a default is used; currently, this is “im-” plus TelepathyGLib.Protocol :protocol-name.

New in version 0.11.11.

TelepathyGLib.Protocol.props.param_names¶

Name:: param-names
Type:: [str]
Default Value:: []
Flags:: READABLE

A list of parameter names supported by this connection manager for this protocol, or None if %TP_PROTOCOL_FEATURE_PARAMETERS has not been prepared.

New in version 0.11.11.

TelepathyGLib.Protocol.props.protocol_name¶

Name:: protocol-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The machine-readable name of the protocol, taken from the Telepathy D-Bus Interface Specification, such as “jabber” or “local-xmpp”.

New in version 0.11.11.

TelepathyGLib.Protocol.props.protocol_properties_vardict¶

Name:: protocol-properties-vardict
Type:: GLib.Variant
Default Value:: None
Flags:: READABLE

The immutable properties of this Protocol, as provided at construction time. This is a #G_VARIANT_TYPE_VARDICT GLib.Variant, which must not be modified.

If the immutable properties were not provided at construction time, the %TP_PROTOCOL_FEATURE_PARAMETERS and %TP_PROTOCOL_FEATURE_CORE features will both be unavailable, and this TelepathyGLib.Protocol object will only be useful as a way to access lower-level D-Bus calls.

New in version 0.23.3.

TelepathyGLib.Protocol.props.vcard_field¶

Name:: vcard-field
Type:: str
Default Value:: None
Flags:: READABLE

The most common vCard field used for this protocol’s contact identifiers, normalized to lower case, or None if there is no such field or the %TP_PROTOCOL_FEATURE_CORE feature has not been prepared.

New in version 0.11.11.