Implementing Custom Connection Managers

This document has been reviewed for maemo 4.0.

This guide introduces briefly how to implement a custom connection manager plug-in for the Internet Tablet OS. The messaging framework in Internet Tablet OS is based on Telepathy framework architecture.

Telepathy provides D-Bus-based framework that unifies all forms of real-time communication, such as instant messaging, IRC, voice and video over Internet. The framework provides an interface for plug-ins 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 more detailed information and source code examples, see the Telepathy framework specification by Freedesktop.org.

Since the connection manager uses D-Bus for communication, it can be implemented using any language supporting D-Bus communication, even an interpreted language such as Python. However, in order to enable running on Internet tablets natively, C or C++ is currently preferred.

Several open source Telepathy connection manager implementations already exist. See, for instance, Gabble and Idle projects. In maemo 4.0, there is a source package of telepathy-gabble that has been modified for maemo platform and packaged as a DEB package.

The package can be downloaded from the 4.0 repository. The package can be built the usual way with dpkg-buildpackage.

Telepathy connection managers establish the actual connections to IM or VoIP servers. A connection manager provides support for one or more connection protocols, e.g. SIP. Connection managers are started using D-Bus service activation, and they present a connection manager object to the bus. A connection can be established 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
		The following well-known values should be used when applicable:

    		   * aim - AOL Instant Messenger
    		   * gadugadu - Gadu-Gadu
    		   * groupwise - Novell Groupwise
    		   * icq - ICQ
    		   * irc - Internet Relay Chat
    		   * jabber - Jabber (XMPP)
    		   * msn - MSN Messenger
    		   * napster - Napster
    		   * silc - SILC
    		   * sip - Session Initiation Protocol (SIP)
    		   * trepia - Trepia
    		   * yahoo - Yahoo! Messenger
    		   * zephyr - Zephyr

		RequestConnection ( s: proto, a{sv}: parameters ) -> so
		Signals:		
		NewConnection ( s: bus_name, o: object_path, s: proto )
		Sets of flags:
		Conn_Mgr_Param_Flags
		

The connection object provides the interfaces for basic connection signaling as well as for 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 )
		

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 the needs of the real-time communication protocol. For example, a text channel provides methods to send messages, and is able to send 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 )
		
		

The connection interfaces can handle special needs of the connection protocol, such as aliasing, which means that contacts can have an alias that they can change via the server. The D-Bus interfaces are briefly presented below. More details can be found in the specification.

		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 )