telepathy/ service-profile-v1

Service Profiles

Synopsis

Service Profiles are intended to describe variants of the basic protocols supported by telepathy CMs (Connection Managers): An example of this would be Google Talk vs Facebook chat vs Jabber/XMPP - Google Talk is a specific case of XMPP with well-known capabilities, quirks and settings, and Facebook chat is a subset of the standard XMPP offering.

Since there is a lot of common content/use overlap between Telepathy profiles and libaccounts services, the intention here is to describe a single file format that can and will be shared by both.

A service is uniquely identified by its name: When there is more than one possible choice of CM for a protocol, the preferred CM on any given platform is allowed to name its service profile based on the name of the service alone, and any other CMs profiles that represent the service should be named by prepending the CM name to the service name, separated by a dash '-'.

Details

XMLNS Namespace

The XMLNS for service profiles is http://telepathy.freedesktop.org/wiki/service-profile-v1 A parser/reader/user of a service profile is expected to ignore (for telepathy purposes) any attributes or tags not in this namespace - other users of the file (such as libaccounts) which have their own information storage requirements should use a different namespace for any tags or attributes they add to the service profile file.

A service profile is expected to provide the following information:

service

<service xmlns="http://telepathy.freedesktop.org/wiki/service-profile-v1"
         id="google-talk"
         type="IM"
         provider="google"
         manager="gabble"
         protocol="jabber"
         icon="gtalk-icon">

id

mandatory

The unique name of the service. The preferred CM on a given platform is allowed to have a profile identified by service alone (eg "google-talk").

Any other CMs on the platform should be named -

Examples: google-talk, haze-google-talk

type

mandatory

The type of the service: In general, services of interest to both libaccounts and telepathy should be of type 'IM': Other service types exist but are unlikely to affect telepathy in any way

manager

mandatory

The name of the CM (connection manager)

Examples: gabble, haze

protocol

mandatory

The standard telepathy name for the protocol over which this service is provided.

Examples: jabber

provider

optional

The name of the vendor/organisation/provider who actually runs the service to which this profile applies.

Examples: google, facebook

icon

optional

The base of the icon name for this service (to be looked for in the standard locations for icons used by the rest of the framework). Not explected to include either the type extension or the XxY size information, as these are considered to be entirely the domain of the UI.

Examples: gtalk-icon, fb-icon

name

mandatory

Human-readable name (possibly including required branding and so forth) for the service in question 

    <name>Google``Talk™</name>

parameters

optional

The CM parameters which describe the service: These can be mandatory, in which case the user shold not be allowed to alter them by the UI, as they define the service (google talk accounts must connect to the actual google server, for example) or optional, in which case they merely specify defaults ehich may differ from the CM's defaults.

These parameters are typed (with dbus types), so that libaccounts and telepathy can share the information. It is considered an error for the type of a parameter to differ from the type specified by the CM, although parsers are not required to enforce this (as they may be used in a context where the CM is unavailable and cannot be queried)

Examples:

  • server, port, old-ssl (facebook, mandatory)
  • fallback-conference-server (google, optional) 
    <parameters>
      <parameter name="server"  type="s" mandatory="1">talk.google.com</parameter>
      <parameter name="port"    type="u" mandatory="1">5223</parameter>
      <parameter name="old-ssl" type="b" mandatory="1"
                 label="Use old-style SSL">1</parameter>
      <parameter name="fallback-conference-server">conference.jabber.org</parameter>
    </parameters>

The parameter tag has the following defined attributes:

  • name
    • string: The CM's name for this is (necessarily) canonical
  • type
    • string: (generally one character): the DBus type of the parameter
  • label
    • string: the human-readable label (if any) for the parameter
  • mandatory
    • boolean: (0 or 1, default 0): whether the value is fixed for this particular service

presences

optional

A service can support a subset of the presences supported by a given protocol, and/or have service specific names for the standard presences.

A specified presence in this section is considered to override any properties (label, icon, [default] extended message) of the standard entry for said presence in the CM.

A presence may also be disabled, in which case the UI should not offer it as a choice to the user at all, as the service is not considered to support it.

Examples: 

    <presences allow-others="1">
      <presence id="available" label="Online"  icon="gtalk-online"/>
      <presence id="offline"   label="Offline"/>
      <presence id="away"      label="Gone"/>
      <presence id="hidden"    disabled="1"/>
    </presences>

The presences tag has the following attributes:

  • allow-others

    • boolean (0 or 1, default 0): whether the any standard CM presences not mentioned here are still supported The presence tag supports the following attributes:

  • id

    • string: the telepathy presence id string
  • label
    • string: the label for this presence, if it differs from the CM default
  • icon
    • string: the service specific icon for this presence, if any
  • message
    • boolean: (0 or 1, default 0): if true, a user-defined text message can be attached to this presence
  • disabled
    • boolean (0 or 1, default 0): if true, this presence is not supported

unsuported channel classes

optional

Some services do not support the full range of channels that the protocol & CM are (in general) capable of: This item lists those channel classes which are not available on the service.

Classes are defined (as in an ensure channel or create channel request) by a list of property/value pairs (an a{sv} in DBus terms):

Example: 

    <unsupported-channel-classes>
      <!-- this service doesn't support text roomlists -->
      <channel-class>
        <property name="org.freedesktop.Telepathy.Channel.TargetHandleType"
                  type="u">3</property>
        <property name="org.freedesktop.Telepathy.Channel.ChannelType"
                  type="s">org.freedesktop.Telepathy.Channel.Type.Text</property>
      </channel-class>
      <channel-class>
       ⋮
      </channel-class>
    </unsupported-channel-classes>

The property tag has the following attributes:

  • name
    • string: the telepathy DBus property of the channel
  • type
    • string (generally one character): the [DBus] type of the property

Example

<service xmlns="http://telepathy.freedesktop.org/wiki/service-profile-v1"
         id="google-talk"
         type="IM"
         provider="google"
         manager="gabble"
         protocol="jabber"
         icon="gtalk-icon">
  <name>Google``Talk™</name>

  <parameters>
    <parameter name="server"  type="s" mandatory="1">talk.google.com</parameter>
    <parameter name="port"    type="u" mandatory="1">5223</parameter>
    <parameter name="old-ssl" type="b" mandatory="1"
               label="Use old-style SSL">1</parameter>
    <parameter name="fallback-conference-server">conference.jabber.org</parameter>
  </parameters>

  <parameters>
    <parameter name="server"  type="s" mandatory="1">profile.com</parameter>
    <parameter name="port"    type="u" mandatory="1">1111</parameter>
  </parameters>

  <presences allow-others="1">
    <presence id="available" label="Online"  icon="online"/>
    <presence id="offline"   label="Offline"/>
    <presence id="away"      label="Gone"/>
    <presence id="hidden"    disabled="1"/>
  </presences>

  <unsupported-channel-classes>
    <!-- this service doesn't support text roomlists -->
    <channel-class>
      <property name="org.freedesktop.Telepathy.Channel.TargetHandleType"
                type="u">3</property>
      <property name="org.freedesktop.Telepathy.Channel.ChannelType"
                type="s">org.freedesktop.Telepathy.Channel.Type.Text</property>
    </channel-class>
  </unsupported-channel-classes>
</service>