Interface Connection

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Contact Attributes | Types

Methods

Connect () → nothing
Disconnect () → nothing
AddClientInterest (as: Tokens) → nothing
RemoveClientInterest (as: Tokens) → nothing
GetContactAttributes (au: Handles, as: Interfaces) → a{ua{sv}}: Attributes
GetContactByID (s: Identifier, as: Interfaces) → u: Handle, a{sv}: Attributes

Signals

SelfContactChanged (u: Self_Handle, s: Self_ID)
ConnectionError (s: Error, a{sv}: Details)
StatusChanged (u: Status, u: Reason)

Properties

Interfaces as (DBus_Interface_List) Read only
SelfHandle u (Contact_Handle) Read only
SelfID s Read only
Status u (Connection_Status) Read only
RequestableChannelClasses a(a{sv}as) (Requestable_Channel_Class_List) Read only

Contact Attributes

im.telepathy.v1.Connection/contact-id s

Types

Handle Simple Type u
Contact_Handle Simple Type u
Room_Handle Simple Type u
Contact_Attribute Simple Type s
Entity_Type Enum u
Connection_Status Enum u
Connection_Status_Reason Enum u
Single_Contact_Attributes_Map Mapping a{sv}
Contact_Attributes_Map Mapping a{ua{sv}}
Channel_Class Mapping a{sv}
Requestable_Channel_Class Struct (a{sv}as)
Changed in 0.17.10. Previously, the account part of Connection bus names/object paths was allowed to have more than one component (i.e. contain dots or slashes), resulting in Connection bus names and object paths with more than 7 components. We now restrict Connection bus names/object paths to have exactly 7 components.
Changed in 0.17.23. The Requests and Contacts interfaces are now mandatory. Their functionality will be merged into the main Connection interface at some point in future.
Changed in 0.99.1. All deprecated types, methods, and signals have been removed from this interface including anything to do with handle reference counting.
Changed in 0.99.6. The former Contacts interface is now part of Connection.
Objects implementing this interface must also implement:

Description

This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and receive channels of differing types (such as text channels or streaming media channels) which are used to carry out further communication.

In order to allow Connection objects to be discovered by new clients, the object path and well-known bus name MUST be of the form /im/telepathy/v1/Connection/cmname/proto/account and im.telepathy.v1.Connection.cmname.proto.account where:

account SHOULD be formed such that any valid distinct connection instance on this protocol has a distinct name. This might be formed by including the server name followed by the user name (escaped via some suitable mechanism like telepathy-glib's tp_escape_as_identifier() function to preserve uniqueness); on protocols where connecting multiple times is permissable, a per-connection identifier might be necessary to ensure uniqueness.

Clients MAY parse the object path to determine the connection manager name and the protocol, but MUST NOT attempt to parse the account part. Connection managers MAY use any unique string for this part.

As well as the methods and signatures below, arbitrary interfaces may be provided by the Connection object to represent extra connection-wide functionality, such as the Connection.Interface.Presence for receiving and reporting presence information, and Connection.Interface.Aliasing for connections where contacts may set and change an alias for themselves. These interfaces can be discovered using the Interfaces property.

Contacts, rooms, and server-stored lists (such as subscribed contacts, block lists, or allow lists) on a service are all represented by immutable handles, which are unsigned non-zero integers which are valid only for the lifetime of the connection object, and are used throughout the protocol where these entities are represented, allowing simple testing of equality within clients.

Zero as a handle value is sometimes used as a "null" value to mean the absence of a contact, room, etc.

Handles have per-type uniqueness, meaning that every (handle type, handle number) tuple is guaranteed to be unique within a connection for the lifetime of the connection and that a handle alone (without its type) is meaningless or ambiguous.

Methods

(Permalink)

Connect () → nothing

Request that the connection be established. This will be done asynchronously and errors will be returned by emitting StatusChanged signals.

Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.

(Permalink)

Disconnect () → nothing

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.
(Permalink)

AddClientInterest (as: Tokens) → nothing

Added in 0.21.3.

Parameters

  • Tokens — as

    • Interfaces or parts of interfaces in which to register an interest, represented by either a DBus_Interface, or a string prefixed with a DBus_Interface.

    If the Connection does not support one of these tokens, this is not considered to be an error; the unsupported token is simply ignored.

Register a client's interest in notifications related to one or more interfaces.

Groups of notifications are identified by a token which is either a D-Bus interface name, or a string that starts with a D-Bus interface name. The meaning of each token is given by that D-Bus interface, which MUST define it in its documentation.

Rationale:

Initially, all interests are in entire interface, but allowing other strings allows subscription to part of an interface; for instance, an interest in ...MailNotification/count could track the number of messages without caring about their detailed content.

For each token with which this method interacts, the Connection tracks an "interest count" (like a reference count) for each unique bus name that has called this method. When a client calls this method, for each token, the interest count for its unique bus name is incremented; when RemoveClientInterest is called, all interest counts for that unique bus name are decremented. If the unique bus name leaves the bus (for instance, if the client crashes or exits), all interest counts for that unique bus name are set to zero.

The Connection can then use these reference counts to avoid subscribing to protocol-level notifications unless at least one client has a non-zero interest count for the relevant token.

Rationale:

This method exists to reduce memory and network overhead when there is no active subscription.

One situation where this is useful is Location1: on XMPP, location updates are received over PEP. If the Connection advertises the geoloc+notify capability, it will be sent location updates for all contacts. To avoid consuming resources for this, the connection should avoid advertising that capability until a client has expressed an interest in contacts' locations.

Another example of a protocol that benefits from this method is the Google XMPP Mail Notification extension, which can be used to implement MailNotification1. In this protocol, the CM receives a notification that something has changed, but to get more information, the CM must request this information. Knowing that nobody is currently interested in this information, the CM can avoid generating useless network traffic. Similarly, the CM may free the list of unread messages to reduce memory overhead.

If this method is called for an interface that might require protocol-level subscription, but the connection cannot set up that subscription yet (for instance because the Status is not Connected yet), the Connection MUST remember the client's interest, and attempt to subscribe to the appropriate protocol feature when this becomes possible.

Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.

Rationale:

The only reason it could fail is if it's unimplemented, in which case the only thing the client can usefully do is to proceed as if it had succeeded.

(Permalink)

RemoveClientInterest (as: Tokens) → nothing

Added in 0.21.3.

Parameters

  • Tokens — as

    • Interfaces or parts of interfaces that were previously passed to AddClientInterest.

Release an interest registered using AddClientInterest. See that method's documentation for details.

Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.

Rationale:

The only reasons it could fail are if it's unimplemented, or if the client's reference-counting is wrong and it has tried to remove a client interest that it did not add. In both cases, there's nothing the client could do about it.

(Permalink)

GetContactAttributes (au: Handles, as: Interfaces) → a{ua{sv}}: Attributes

Parameters

  • Handles — au (Contact_Handle_List)
    • An array of handles representing contacts.
  • Interfaces — as (DBus_Interface_List)

    • A list of strings indicating which D-Bus interfaces the calling process is interested in. All supported attributes from these interfaces, whose values can be obtained without additional network activity, will be in the reply.

    Attributes from the interface im.telepathy.v1.Connection are always returned, and need not be requested explicitly.

    As well as returning cached information immediately, the connection MAY start asynchronous requests to obtain better values for the contact attributes. If better values are later obtained by this process, they will be indicated with the usual signals (such as AliasesChanged).

    Rationale:
    For instance, an XMPP connection manager could download vCards in response to a request for Aliasing1 attributes.

Returns

  • Attributes — a{ua{sv}} (Contact_Attributes_Map)

    • A dictionary mapping the contact handles to contact attributes. If any of the requested handles are in fact invalid, they are simply omitted from this mapping. If contact attributes are not immediately known, the behaviour is defined by the interface; the attribute should either be omitted from the result or replaced with a default value.

    Each contact's attributes will always include at least the identifier that would be obtained by inspecting the handle (im.telepathy.v1.Connection/contact-id).

Return any number of contact attributes for the given handles.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
(Permalink)

GetContactByID (s: Identifier, as: Interfaces) → u: Handle, a{sv}: Attributes

Added in 0.27.0.

Parameters

  • Identifier — s
    • An identifier representing a contact.
  • Interfaces — as (DBus_Interface_List)

    • A list of strings indicating which D-Bus interfaces the calling process is interested in. All supported attributes from these interfaces, whose values can be obtained without additional network activity, will be in the reply.

    See GetContactAttributes for details.

Returns

  • Handle — u (Contact_Handle)

    • The contact's handle

  • Attributes — a{sv} (Single_Contact_Attributes_Map)

    • All supported attributes of the contact on the given interfaces that can be returned without network round-trips. If contact attributes are not immediately known, the behaviour is defined by the interface; the attribute should either be omitted from the result or replaced with a default value.

    The contact's attributes will always include at least the identifier that would be obtained by inspecting the handle (org.freedesktop.Telepathy.Connection/contact-id).

Return any number of contact attributes for the given identifier.
Rationale:
This is for a single identifier to make it simpler to use for the most common use case. For multiple contacts case, GetContactAttributes should be used.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.

Signals

(Permalink)

SelfContactChanged (u: Self_Handle, s: Self_ID)

Added in 0.27.2. Clients MAY assume that if the SelfHandle and SelfID property exists, this signal will be emitted when necessary.

Parameters

  • Self_Handle — u (Contact_Handle)
    • The new value of the SelfHandle property.
  • Self_ID — s
    • The new value of the SelfID property.
Emitted whenever the SelfHandle and SelfID property changes. If the connection is not yet in the CONNECTED state, this signal is not guaranteed to be emitted.
(Permalink)

ConnectionError (s: Error, a{sv}: Details)

Parameters

  • Error — s (DBus_Error_Name)
    • The name of a D-Bus error describing the error that occurred, which may correspond to a Connection_Status_Reason, or may be a more specific Telepathy error (such as im.telepathy.v1.Error.ConnectionRefused for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace.
    Rationale:
    For instance, a SIP connection manager could signal "402 Payment Required" as an error in a connection-manager-specific namespace, or a link-local XMPP implementation that used Avahi could provide the error given to it by the avahi-daemon.
  • Details — a{sv} (String_Variant_Map)

    • Additional information about the error, which may include the following well-known keys:

    debug-message (s)
    Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances
    server-message (s)
    A human-readable message from the server explaining what happened. This may be in the user's native language, or in the server operator's native language, or even in Lojban.
    user-requested (b), expected-hostname (s), certificate-hostname (s)
    The same details defined in TLS_Certificate_Rejection.

Emitted when an error occurs that renders this connection unusable.

Whenever this signal is emitted, it MUST immediately be followed by a StatusChanged signal with status Connection_Status_Disconnected and an appropriate reason code.

Connection managers SHOULD emit this signal on disconnection, but need not do so. Clients MUST support connection managers that emit StatusChanged(Disconnected, ...) without first emitting ConnectionError.

Rationale:

This signal provides additional information about the reason for disconnection. The reason for connection is always straightforward - it was requested - so it does not need further explanation. However, on errors, it can be useful to provide additional information.

The Connection_Status_Reason is not given here, since it will be signalled in StatusChanged. A reasonable client implementation would be to store the information given by this signal until StatusChanged is received, at which point the information given by this signal can be used to supplement the StatusChanged signal.

(Permalink)

StatusChanged (u: Status, u: Reason)

Parameters

  • Status — u (Connection_Status)
    • An integer indicating the new status, as defined by ConnectionStatus
  • Reason — u (Connection_Status_Reason)
    • An integer indicating the reason for the status change, as defined by ConnectionStatusReason
Emitted when the status of the connection changes. All states and reasons have numerical values, as defined in ConnectionStatus and ConnectionStatusReason.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

Interfaces — as (DBus_Interface_List)

Read only
Added in 0.19.2.

The set of optional interfaces supported by this connection. Before the connection status changes to CONNECTED, this property may change at any time, but it is guaranteed that interfaces will only be added, not removed. After the connection status changes to CONNECTED, this property cannot change further.

There is no explicit change notification; reasonable behaviour for a client would be to retrieve the interfaces list once initially, and once more when it becomes CONNECTED.

Rationale:

In some connection managers, certain capabilities of a connection are known to be implemented for all connections (e.g. support for Presence), and some interfaces (like Presence) can even be used before connecting. Other capabilities may or may not exist, depending on server functionality; by the time the connection goes CONNECTED, the connection manager is expected to have evaluated the server's functionality and enabled any extra interfaces for the remainder of the Connection's lifetime.

As a special case, the mandatory Requests interface SHOULD NOT be listed in this property.

Rationale:

It has been mandatory since Telepathy 0.18 in 2009, and contains essential functionality for this interface, so there seems no point in wasting bytes on capability discovery for it.

(Permalink)

SelfHandle — u (Contact_Handle)

Read only
Added in 0.17.10.
The handle which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the SelfContactChanged signal. If the connection is not yet in the CONNECTED state, the value of this property MAY be zero.
(Permalink)

SelfID — s

Read only
Added in 0.27.2.
The identifier which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the SelfContactChanged signal. If the connection is not yet in the CONNECTED state, the value of this property MAY be empty string.
(Permalink)

Status — u (Connection_Status)

Read only
Added in 0.19.2.

The current status of the connection. Change notification is via the StatusChanged signal.

If retrieval of property succeeds and yields the value Disconnected, this indicates that the connection has not yet been established. If connection has been attempted and failed, the Connection object SHOULD be removed from the bus entirely, meaning that retrieval of this property SHOULD fail.

(Permalink)

RequestableChannelClasses — a(a{sv}as) (Requestable_Channel_Class_List)

Read only
Added in 0.17.11. (as stable API)

The classes of channel that are expected to be available on this connection, i.e. those for which CreateChannel can reasonably be expected to succeed. User interfaces can use this information to show or hide UI components.

This property cannot change after the connection has gone to state Connection_Status_Connected, so there is no change notification (if the connection has context-dependent capabilities, it SHOULD advertise support for all classes of channel that it might support during its lifetime). Before this state has been reached, the value of this property is undefined.

Rationale:

This is not on an optional interface, because connection managers can always offer some sort of clue about the channel classes they expect to support (at worst, they can announce support for everything for which they have code).

Contact Attributes

Attributes that a contact can have, accessed with the im.telepathy.v1.Connection.Interface.Contacts interface.
(Permalink)

im.telepathy.v1.Connection/contact-id — s

The normalized contact's identifier. Not necessarily the same string as passed to GetContactByID. As a special case, this is always present in the result of GetContactAttributes and GetContactByID, whether it was explicitly requested or not.

Types

Simple Type (Permalink)

Handle — u

An unsigned 32-bit integer representing a string. A handle is meaningless on its own, and must be paired with a Entity_Type. Among nonzero handles with the same Entity_Type, there is a bidirectional mapping between handles and strings.

The handle 0 is special, and represents the absence of a contact, room etc. It corresponds to None.

Simple Type (Permalink)

Contact_Handle — u

A nonzero Handle of type Contact, or 0 to represent the absence of a contact (None).
Simple Type (Permalink)

Room_Handle — u

A nonzero Handle of type Room, or 0 to represent the absence of a room (None).
Simple Type (Permalink)

Contact_Attribute — s

A DBus_Interface, followed by a slash '/' character and an identifier for an attribute defined by that interface. The attribute identifier SHOULD be in lower case.
Rationale:
These aren't D-Bus core Properties, and we want them to look visibly different.
Enum (Permalink)

Entity_Type — u

Enumeration describing the type of entity with which a channel communicates.

For instance, a text chat or VoIP call with a person or automated system has entity type Contact, a text chatroom or a VoIP call to a conferencing system ideally has entity type Room, and a channel listing chatrooms available on a server has entity type None.

  • None (0)

    • The absence of a entity, Contact, Room, etc. For instance, ContactSearch1, RoomList1, ServerAuthentication1 and ServerTLSConnection1 channels do not communicate with a specific entity, so they have this channel type.

    This entity type is also used for chatrooms that cannot be addressed by name (so users cannot join by typing a name or number, only by being invited), such as multi-user "switchboards" in MSNP.

    Where this appears alongside a Handle and/or Identifier, the handle MUST be 0 and the identifier MUST be the empty string.

  • Contact (1)

    • A contact, i.e. a person or automated system.

    The corresponding identifier is a normalized form of the contact's unique machine-readable identifier in this particular protocol (such as an XMPP JID, SIP URI, AIM screen-name, ICQ number or IRC nickname). For instance, any parts of the identifier that are defined to be case-insensitive by the protocol SHOULD be normalized to lower-case.

    In protocols where conferencing systems cannot reliably be distinguished from individuals, conferencing systems MAY also appear with Contact.

    Rationale:
    For instance, calls to/from SIP teleconferencing "rooms" typically appear as a simple SIP URI
  • Room (2)

    • A chatroom or teleconferencing system that can be addressed by name.

    The corresponding identifier is a normalized form of the room's unique machine-readable identifier in this particular protocol, such as the JID "jdev@conference.jabber.org" on XMPP, or the channel name "#telepathy" on IRC.

  • Self (3)

    • Not used within Telepathy itself, but reserved for use by telepathy-logger.

    Rationale:
    telepathy-logger uses this type to represents the owner of the account whose channel has been logged to. We don't need this concept in Telepathy itself but it's convenient to use the same enum across the whole API.
Enum (Permalink)

Connection_Status — u

  • Connected (0)
    • The connection is fully connected and all methods are available.
  • Connecting (1)
    • Connect has been called but the connection has not yet been established. Some methods may fail until the connection has been established.
  • Disconnected (2)
    • If this is retrieved from Status, it indicates that connection has not yet been attempted. If seen in a StatusChanged signal, it indicates that the connection has failed; the Connection object SHOULD be removed from D-Bus immediately, and all subsequent method calls SHOULD fail.
Enum (Permalink)

Connection_Status_Reason — u

A reason why the status of the connection changed. Apart from Requested, the values of this enumeration only make sense as reasons why the status changed to Disconnected.

  • None_Specified (0)

    • There is no reason set for this state change. Unknown status reasons SHOULD be treated like this reason.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Disconnected.

  • Requested (1)

    • The change is in response to a user request. Changes to the Connecting or Connected status SHOULD always indicate this reason; changes to the Disconnected status SHOULD indicate this reason if and only if the disconnection was requested by the user.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cancelled.

  • Network_Error (2)

    • There was an error sending or receiving on the network socket.

    When the status changes from Connecting to Disconnected for this reason, the equivalent D-Bus error is either im.telepathy.v1.Error.NetworkError, im.telepathy.v1.Error.ConnectionRefused, im.telepathy.v1.Error.ConnectionFailed or some more specific error.

    When the status changes from Connected to Disconnected for this reason, the equivalent D-Bus error is either im.telepathy.v1.Error.NetworkError, im.telepathy.v1.Error.ConnectionLost or some more specific error.

  • Authentication_Failed (3)

    • The username or password was invalid.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.AuthenticationFailed.

  • Encryption_Error (4)

    • There was an error negotiating SSL on this connection, or encryption was unavailable and require-encryption was set when the connection was created.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.EncryptionNotAvailable if encryption was not available at all, or im.telepathy.v1.Error.EncryptionError if encryption failed.

  • Name_In_Use (5)

    • In general, this reason indicates that the requested account name or other identification could not be used due to conflict with another connection. It can be divided into three cases:

    • If the status change is from Connecting to Disconnected and the 'register' parameter to RequestConnection was present and true, the requested account could not be created on the server because it already exists. The equivalent D-Bus error is im.telepathy.v1.Error.RegistrationExists.
    • If the status change is from Connecting to Disconnected but the 'register' parameter is absent or false, the connection manager could not connect to the specified account because a connection to that account already exists. The equivalent D-Bus error is im.telepathy.v1.Error.AlreadyConnected.
      Rationale:
      In some protocols, like XMPP (when connecting with the same JID and resource as an existing connection), the existing connection "wins" and the new one fails to connect.
    • If the status change is from Connected to Disconnected, the existing connection was automatically disconnected because a new connection to the same account (perhaps from a different client or location) was established. The equivalent D-Bus error is im.telepathy.v1.Error.ConnectionReplaced.
      Rationale:
      In some protocols, like MSNP (when connecting twice with the same Passport), the new connection "wins" and the existing one is automatically disconnected.
  • Cert_Not_Provided (6)

    • The server did not provide a SSL certificate.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.NotProvided.

  • Cert_Untrusted (7)

    • The server's SSL certificate is signed by an untrusted certifying authority. This error SHOULD NOT be used to represent a self-signed certificate: use the more specific Cert_Self_Signed reason for that.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.Untrusted.

  • Cert_Expired (8)

    • The server's SSL certificate has expired.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.Expired.

  • Cert_Not_Activated (9)

    • The server's SSL certificate is not yet valid.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.NotActivated.

  • Cert_Hostname_Mismatch (10)

    • The server's SSL certificate did not match its hostname.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.HostnameMismatch.

  • Cert_Fingerprint_Mismatch (11)

    • The server's SSL certificate does not have the expected fingerprint.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.FingerprintMismatch.

  • Cert_Self_Signed (12)

    • The server's SSL certificate is self-signed.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.SelfSigned.

  • Cert_Other_Error (13)

    • There was some other error validating the server's SSL certificate.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.Invalid.

  • Cert_Revoked (14)

    • The server's SSL certificate has been revoked.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.Revoked.

  • Cert_Insecure (15)

    • The server's SSL certificate uses an insecure algorithm, or is cryptographically weak.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.Insecure.

  • Cert_Limit_Exceeded (16)

    • The length in bytes of the server certificate, or the depth of the sever certificate chain exceed the limits imposed by the crypto library.

    When disconnected for this reason, the equivalent D-Bus error is im.telepathy.v1.Error.Cert.LimitExceeded

Mapping (Permalink)

Single_Contact_Attributes_Map — a{sv}

Some of the attributes of a single contact.
  • Attribute — s (Contact_Attribute)
    • The name of the attribute
  • Value — v
    • The value of the attribute
Mapping (Permalink)

Contact_Attributes_Map — a{ua{sv}}

Mapping returned by GetContactAttributes, representing a collection of Contacts and their requested attributes.
Mapping (Permalink)

Channel_Class — a{sv}

Added in 0.17.11. (as stable API)

Mapping representing a class of channels that can be requested from a connection manager, can be handled by a user interface, are supported by a contact, etc.

Classes of channel are identified by the fixed values of a subset of their properties.

Channel classes SHOULD always include the keys im.telepathy.v1.Channel.ChannelType and im.telepathy.v1.Channel.TargetEntityType.

  • Key — s (DBus_Qualified_Member)
    • A D-Bus interface name, followed by a dot and a D-Bus property name.
  • Value — v
    • The value of the property.
Struct (Permalink)

Requestable_Channel_Class — (a{sv}as)

Added in 0.17.11. (as stable API)

Structure representing a class of channels that can be requested, identified by a set of properties that identify that class of channel.

Rationale:

This will often just be the channel type and the handle type, but can include other properties of the channel - for instance, encrypted channels might require properties that unencrypted channels do not, like an encryption key.

In some cases, these classes of channel may overlap, in the sense that one class fixes all the properties that another class does, plus some more properties.

Rationale:

For older clients to still be able to understand how to request channels in the presence of a hypothetical "encryption" interface, we'd need to represent it like this:

  • class 1: ChannelType = Text, TargetEntityType = CONTACT
  • class 2: Channel.ChannelType = Text, Channel.TargetEntityType = CONTACT, Encryption.Encrypted = TRUE
  • Fixed_Properties — a{sv} (Channel_Class)

    • The property values that identify this requestable channel class. These properties MUST be included in requests for a channel of this class, and MUST take these values.

    Clients that do not understand the semantics of all the Fixed_Properties MUST NOT request channels of this class, since they would be unable to avoid making an incorrect request.

    This implies that connection managers wishing to make channels available to old or minimal clients SHOULD have a channel class with the minimum number of Fixed_Properties, and MAY additionally have channel classes with extra Fixed_Properties.

    Interface designers SHOULD avoid introducing fixed properties whose types are not serializable in a .manager file.

    Rationale:

    Connection managers with a fixed property that is not serializable cannot have a complete .manager file.

  • Allowed_Properties — as (DBus_Qualified_Member_List)

    • Properties that MAY be set when requesting a channel of this channel type and handle type.

    This array MUST NOT include properties that are in the Fixed_Properties mapping.

    Properties in this array may either be required or optional, according to their documented semantics.

    Rationale:

    For instance, if TargetEntityType takes a value that is not Entity_Type_None, one or the other of TargetHandle and TargetID is required. Clients are expected to understand the documented relationship between the properties, so we do not have separate arrays of required and optional properties.