This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
An object representing a protocol for which this
Each Protocol object has the same well-known bus name as its parent
ConnectionManager. Its object path is formed by taking the
ConnectionManager's object path and appending '/', followed by the
This is the same as the representation of protocol names
in Account object paths, and in Connection object paths and bus
names. For instance, telepathy-gabble and telepathy-salut would
implement objects at
/org/freedesktop/Telepathy/ConnectionManager/gabble/jabber
and
/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp
,
respectively.
If the ConnectionManager has a .manager file, each Protocol's immutable properties must be represented in that file; the representation is described as part of the documentation for each property. For instance, a very simple ConnectionManager with one Protocol might be represented like this:
[ConnectionManager] Interfaces= [Protocol example] Interfaces= ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests; param-account=s required param-password=s required secret RequestableChannelClasses=text; VCardField=x-example EnglishName=Example Icon=im-example [text] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=1 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
A list of interfaces supported by this Protocol object.
This property is immutable, and should not be confused with
Connection managers with a .manager
file
(as described as part of the
.manager
file, using the key Interfaces
. The corresponding value
is a list of D-Bus interface names, each followed by a semicolon.
The parameters which must or may be provided to the
Connection managers with a .manager
file
(as described as part of the
.manager
file via keys of the form param-p
and
default-p
, as documented in the
A list of interface names which might be in the
This property is immutable, and should not be confused with
Connection managers with a .manager
file
MUST cache this property in the protocol's section of the
.manager
file, using the key
ConnectionInterfaces
. The corresponding value
is a list of D-Bus interface names, each followed by a semicolon.
A list of channel classes which might be requestable from a
Whether a Connection will have all, some or none of these requestable channel classes depends on server capabilities; similarly, individual contacts are not guaranteed to support all of these channel classes.
This property is immutable.
Connection managers with a .manager
file
MUST cache this property in the protocol's section of the
.manager
file, using the key
RequestableChannelClasses
. The corresponding value
is a list of opaque strings, each followed by a semicolon; each
of those strings is the name of a group in the .manager
file which represents a channel class.
The names of the groups representing channel classes are not significant, and MUST NOT be interpreted. When writing .manager files, authors MAY choose mnemonic group names, generate group names mechanically (e.g. with an incrementing integer), or use some combination of these.
Each group representing a channel class has a key
allowed
which is a list of D-Bus property names
representing allowed parameters. Any other keys that do not contain
a space MUST be ignored. Any key containing a space represents
a fixed property; the key has the form
"propertyname type
", and the value
is encoded in the same way as for the default-p
keys described in the
Connection managers that have channel classes whose fixed
properties are not representable in this form SHOULD NOT have
.manager
files.
For instance, this .manager
file could represent
a connection manager that supports 1-1 Text messages and
StreamedMedia audio calls:
[Protocol jabber] param-account=s required param-password=s required RequestableChannelClasses=rcc0;rcc1; [rcc0] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=1 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; [rcc1] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia org.freedesktop.Telepathy.Channel.TargetHandleType u=1 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio;
The name of the most common vCard field used for this protocol's contact identifiers, normalized to lower case, or the empty string if there is no such field.
For example, this would be x-jabber
for
Jabber/XMPP (including Google Talk), or tel
for
the PSTN.
A more exhaustive list of addressable vCard fields can be found in
the Protocol's Addressing interface's
It is not necessarily valid to interpret contacts' identifiers
as values of this vCard field. For instance, telepathy-sofiasip
supports contacts whose identifiers are of the form
sip:jenny@example.com or tel:8675309, which would not normally
both be represented by any single vCard field. Arbitrary
handles/identifiers as vCard fields are represented
through the Connection's
This is taken from Mission Control profiles as used on Maemo 5. One valid use of this field is to answer the question: given a contact's vCard containing an X-JABBER field, how can you communicate with the contact? By iterating through protocols looking for an x-jabber VCardField, one can build up a list of protocols that handle x-jabber, then offer the user a list of accounts for those protocols and/or the option to create a new account for one of those protocols.
Connection managers with a .manager
file
MUST cache this property in the protocol's section of the
.manager
file if it is non-empty, using the key
VCardField
. The corresponding value
is a string, following the syntax of the "localestring" type from
the Desktop Entry Specification.
The name of the protocol in a form suitable for display to users, such as "AIM" or "Yahoo!", or the empty string if none is available.
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 the Telepathy
Many protocols are named after a company or product which isn't translated in non-English locales. This also provides a fallback display name, for UIs with no prior knowledge of a particular protocol.
If this property's value is empty, clients MAY fall back to using
the Telepathy
Connection managers with a .manager
file
MUST cache this property in the protocol's section of the
.manager
file if it is non-empty, using the key
EnglishName
. The corresponding value
is a string, following the syntax of the "localestring" type from
the Desktop Entry Specification.
The name of an icon in the system's icon theme, such as "im-msn", or the empty string.
This can be used as a default if the
If this property's value is empty, clients MAY fall back to
generating a name based on the
Connection managers with a .manager
file
MUST cache this property in the protocol's section of the
.manager
file if it is non-empty, using the key
Icon
. The corresponding value
is a string, following the syntax of the "localestring" type from
the Desktop Entry Specification.
Return a string which uniquely identifies the account to which the given parameters would connect.
For many protocols, this would return the well-known 'account' parameter. However, for IRC the returned string would be composed from the 'account' (i.e. nickname) and 'server' parameters. AccountManager implementations can use this to form the account-specific part of an Account's object path.
An opaque string suitable for use as the account-specific part of
an
For a pathological case, consider a user signing in as 'me@example.com' with 'server' set to either jabber1.example.com or jabber2.example.com. Both of these should result in me@example.com being returned from this method, even if the user can actually be signed in to those two servers simultaneously.
Attempt to normalize the given contact ID. Where possible, this
SHOULD return the same thing that would be returned by
InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected
If full normalization requires network activity or is otherwise
impossible to do without a
One common example of a best-effort offline normalization differing from the ideal normalization is XMPP.
On XMPP, contacts' JIDs should normally have the resource removed during normalization, but for contacts in a MUC (chatroom), the resource is an integral part of the JID - so the contact JID alice@example.com/Empathy should normalize to alice@example.com, but the in-MUC JID wonderland@conference.example.com/Alice should normalize to itself.
While online, the connection manager has enough context to know which chatrooms the user is in, and can infer from that whether to remove resources, but the best-effort normalization performed while offline does not have this context, so the best that can be done is to remove the resource from all JIDs.
This method MAY simply raise NotImplemented on some protocols.
In link-local XMPP, you can't talk to someone who isn't present on your local network, so normalizing identifiers in advance is meaningless.