Implementing custom connection managers

Introduction

This document has been reviewed for maemo 3.x

This guide gives you a brief introduction on how to implement a custom connection manager plugin for the Internet Tablet OS 2006 or OS 2007. The messaging framework in Internet Tablet OS 2006/2007 is based on Telepathy framework architecture.

Telepathy provides D-Bus based framework that unifies all forms of real time communication like instant messaging, IRC, voice and video over Internet. The framework provides an interface for plugins to extend the protocol support by implementing new connection managers. These new supported protocols can then be used by all client applications that communicate via Telepathy framework architecture.

For any detailed information, see The Telepathy framework specification by the Freedesktop.org.

Since the connection manager uses D-Bus for communication it can be implemented using any language, even interpreted like Python, that supports D-Bus communication. In order to run on Internet tablets natively, however, C or C++ is currently preferred.

Example connection manager implementations

There exists several Telepathy connection manager implementations already in the open source. See, for instance, Gabble and Idle projects. In maemo 3.X there is a source package of telepathy-gabble which has been modified for maemo platform and packaged as a DEB package.

The package can be downloaded from the bora repository. The package can be build the usual way with dpkg-buildpackage.

Connection manager and connections

Telepathy connection managers establish the actual connections to IM or VoIP servers. A connection manager provides support for one or more connection protocols like SIP, for instance. Connection managers are started using D-Bus service activation, and they present a connection manager object to the bus. A connection can be eshtablished by sending a D-Bus message request to the connection manager object. A new D-Bus object is then created to handle the new connection. The D-Bus interface of a connection manager is:

org.freedesktop.Telepathy.ConnectionManager
Methods:
GetParameters ( s: proto ) -> a(susv)
ListProtocols ( ) -> as
RequestConnection ( s: proto, a{sv}: parameters ) -> so
NewConnection ( s: bus_name, o: object_path, s: proto )
		

The connection object provides the interfaces to basic connection signaling as well as requesting communication channels. The D-Bus interface of a connection is:

org.freedesktop.Telepathy.Connection
Methods:
Connect ( ) -> None
Disconnect ( ) -> None
GetInterfaces ( ) -> as
GetProtocol ( ) -> s
GetSelfHandle ( ) -> u
GetStatus ( ) -> u
HoldHandles ( u: handle_type, au: handles ) -> None
InspectHandles ( u: handle_type, au: handles ) -> as
ListChannels ( ) -> a(osuu)
ReleaseHandles ( u: handle_type, au: handles ) -> None
RequestChannel ( s: type, u: handle_type, u: handle, b: suppress_handler ) -> o
RequestHandles ( u: handle_type, as: names ) -> au
Signals:
NewChannel ( o: object_path, s: channel_type, u: handle_type, u: handle, b: suppress_handler )
StatusChanged ( u: status, u: reason )		

Channels and channel types

Communication with the server and other contacts is carried out with instances of various channel types. The interface for creating, closing and handling channels is the following:

org.freedesktop.Telepathy.Channel
Methods:
Close ( ) -> None
GetChannelType ( ) -> s
GetHandle ( ) -> uu
GetInterfaces ( ) -> as
Signals:
Closed ( )
		

Various channel types are supported in the Telepathy framework to match with the nature of the real time communication protocol needs. For example, a text channel provides methods to send messages, and has signals to indicate that messages have been sent and received.

org.freedesktop.Telepathy.Channel.Type.ContactList

org.freedesktop.Telepathy.Channel.Type.ContactSearch
Methods:
GetSearchKeys ( ) -> sa{s(bg)}
GetSearchState ( ) -> u
Search ( a{sv}: terms ) -> None
Signals:
SearchResultReceived ( u: contact, a{sv}: values )
SearchStateChanged ( u: state )
		
org.freedesktop.Telepathy.Channel.Type.StreamedMedia
Methods:
ListStreams ( ) -> a(uuuuuu)
RemoveStreams ( au: streams ) -> None
RequestStreamDirection ( u: stream_id, u: stream_direction ) -> None
RequestStreams ( u: contact_handle, au: types ) -> a(uuuuuu)
Signals:
StreamAdded ( u: stream_id, u: contact_handle, u: stream_type )
StreamDirectionChanged ( u: stream_id, u: stream_direction, u: pending_flags )
StreamError ( u: stream_id, u: errno, s: message )
StreamRemoved ( u: stream_id )
StreamStateChanged ( u: stream_id, u: stream_state )

org.freedesktop.Telepathy.Channel.Type.RoomList
Methods:
GetListingRooms ( ) -> b
ListRooms ( ) -> None
Signals:
GotRooms ( a(usa{sv}): rooms )
ListingRooms ( b: listing )

org.freedesktop.Telepathy.Channel.Type.Text
Methods:
AcknowledgePendingMessages ( au: ids ) -> None
GetMessageTypes ( ) -> au
ListPendingMessages ( b: clear ) -> a(uuuuus)
Send ( u: type, s: text ) -> None
Signals:
LostMessage ( )
Received ( u: id, u: timestamp, u: sender, u: type, u: flags, s: text )
SendError ( u: error, u: timestamp, u: type, s: text )
Sent ( u: timestamp, u: type, s: text )

Additional connection interfaces

The connection interfaces can handle special needs of the connection protocol like aliasing which means that contacts can have an alias which they can change via the server. The D-Bus interfaces are presented here shortly below but see the specification for more details.

org.freedesktop.Telepathy.Connection.Interface.Aliasing
Methods:
GetAliasFlags ( ) -> u
RequestAliases ( au: contacts ) -> as
SetAliases ( a{us}: aliases ) -> None
Signals:
AliasesChanged ( a(us): aliases )

org.freedesktop.Telepathy.Connection.Interface.Avatars
Methods:
GetAvatarRequirements ( ) -> asqqqqu
GetAvatarTokens ( au: contacts ) -> as
RequestAvatar ( u: contact ) -> ays
SetAvatar ( ay: avatar, s: mime_type ) -> s
Signals:
AvatarUpdated ( u: contact, s: new_avatar_token )

org.freedesktop.Telepathy.Connection.Interface.Capabilities
Methods:
AdvertiseCapabilities ( a(su): add, as: remove ) -> a(su)
GetCapabilities ( au: handles ) -> a(usuu)
Signals:
CapabilitiesChanged ( a(usuuuu): caps )

org.freedesktop.Telepathy.Connection.Interface.ContactInfo
Methods:
RequestContactInfo ( u: contact ) -> None
Signals:
GotContactInfo ( u: contact, s: vcard )

org.freedesktop.Telepathy.Connection.Interface.Forwarding
Methods:
GetForwardingHandle ( ) -> u
SetForwardingHandle ( u: forward_to ) -> None
Signals:
ForwardingChanged ( u: forward_to )

org.freedesktop.Telepathy.Connection.Interface.Presence
Methods:
AddStatus ( s: status, a{sv}: parms ) -> None
ClearStatus ( ) -> None
GetStatuses ( ) -> a{s(ubba{ss})}
RemoveStatus ( s: status ) -> None
RequestPresence ( au: contacts ) -> None
SetLastActivityTime ( u: time ) -> None
SetStatus ( a{sa{sv}}: statuses ) -> None
Signals:
PresenceUpdate ( a{u(ua{sa{sv}})}: presence )

org.freedesktop.Telepathy.Connection.Interface.Privacy
Methods:
GetPrivacyMode ( ) -> s
GetPrivacyModes ( ) -> as
SetPrivacyMode ( s: mode ) -> None
Signals:
PrivacyModeChanged ( s: mode )

org.freedesktop.Telepathy.Connection.Interface.Renaming
Methods:
RequestRename ( s: name ) -> None
Signals:
Renamed ( u: original, u: new )