Gabble-specific extensions to the Telepathy interfaces

Copyright (C) 2007 Collabora Limited

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 St, Fifth Floor, Boston, MA 02110-1301 USA

Interfaces

org.freedesktop.Telepathy.ChannelBundle.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

A group of related channels, which should all be dispatched to the same handler if possible.

Bundles currently have no functionality of their own, so clients SHOULD NOT examine this interface, but should instead treat the bundle object-path as an opaque identifier. If more functionality is added to bundles in future, this interface will be used for capability discovery.

The lifetime of a bundle is defined by its component channels - as long as one or more channels whose Bundle property is B exist, the bundle B will also exist.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Interfaces − as (DBus_Interface[]), read-only
A list of the extra interfaces provided by this channel bundle.

org.freedesktop.Telepathy.Channel.FUTURE

This interface is a staging area for future Channel functionality and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

This interface contains functionality which we intend to incorporate into the Channel interface in future. It should be considered to be conceptually part of the core Channel interface, but without API or ABI guarantees.

If we add new functionality to the Channel interface, libraries that use generated code (notably telepathy-glib) will have it as part of their ABI forever, meaning we can't make incompatible changes. By using this interface as a staging area for future Channel functionality, we can try out new properties, signals and methods as application-specific extensions, then merge them into the core Channel interface when we have enough implementation experience to declare them to be stable.

The name is by analogy to Python's __future__ pseudo-module.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Bundle − o, read-only

The ChannelBundle to which this channel belongs.

A channel's Bundle property can never change.

Older connection managers might not have this property. Clients (particularly the channel dispatcher) SHOULD recover by considering each channel to be in a bundle containing only that channel, distinct from all other bundles, which has no additional interfaces.

Added in version 0.17.9. (in Channel.FUTURE pseudo-interface)

org.laptop.Telepathy.BuddyInfo

Implementations of this interface must also implement:

An interface on connections to associate OLPC buddy information with contacts, providing methods for the user to set their own information and retrieve information of contacts. The user is automatically notified when information of contacts that are in his 'subscribe' contact list change.

The following types and names are used to request and set information (except for activities):

s:color
The color name of the buddy. Format used is #RRGGBB,#RRGGBB (stroke,fill).
ay:key
The public key of the buddy.
s:jid
For link-local connections, the JID of the buddy's server account.

Activities are represented by a struct containing:

Methods:

SetProperties ( a{sv}: properties ) → nothing

Set the information of the local user for this connection.

This method may be called before Connect(), in which case the given properties will be advertised as soon as possible after connection (possibly immediately).

Parameters

properties − a{sv}
A dictionary mapping information names to the desired values. This replaces any existing buddy properties completely: any keys which were previously present, but are not present in this dictionary, are deleted.

Possible errors

org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)

GetProperties ( u: contact ) → a{sv}

Get the properties of a particular contact.

Parameters

contact − u
An integer handle for the contact to request his properties for

Returns

properties − a{sv}
A dictionary mapping information names to their values

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)
org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)

SetActivities ( a(su): activities ) → nothing

Set the activities of the local user for this connection.

Parameters

activities − a(su) (Activity[])
An array of structs containing:
  • the identifier of the activity
  • the room handle of the activity channel

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)
org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)

GetActivities ( u: contact ) → a(su)

Get the activities of a particular contact.

Parameters

contact − u
An integer handle for the contact whose activities are to be returned

Returns

activities − a(su) (Activity[])
An array of structs containing:
  • the identifier of the activity
  • the room handle of the activity channel

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)
org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)

SetCurrentActivity ( s: activity, u: channel ) → nothing

Set the current activity of the local user for this connection.

Parameters

activity − s
The identifier of the activity, or the empty string if there is no current activity
channel − u
The room handle of the activity channel, or 0 if there is no current activity

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)
org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)

GetCurrentActivity ( u: contact ) → s, u

Get the current activity of a particular contact.

Parameters

contact − u
An integer handle for the contact whose current activity is to be returned

Returns

activity − s
The identifier of the activity, or "" if there is no current activity
channel − u
The room handle of the activity, or 0 if there is no current activity

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)
org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)

Signals:

PropertiesChanged ( u: contact, a{sv}: properties )

Signal emitted when the properties of a contact from your 'subscribe' contact list are changed.

Parameters

contact − u
An integer handle representing the contact
properties − a{sv}
A dictionary mapping property names to their new values. All properties are included, not just those that have changed.

ActivitiesChanged ( u: contact, a(su): activities )

Signal emitted when the activities of a contact from your 'subscribe' contact list are changed.

Parameters

contact − u
An integer handle representing the contact
activities − a(su) (Activity[])
An array of structs containing:
  • the identifier of the activity
  • the handle of the activity channel

CurrentActivityChanged ( u: contact, s: activity, u: channel )

Signal emitted when the current activity of a contact from your 'subscribe' contact list is changed.

Parameters

contact − u
An integer handle representing the contact
activity − s
The identifier of the activity, or "" if there is no current activity
channel − u
The room handle of the activity channel, or 0 if there is no current activity

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Structure types

Activity − ( s: id, u: room )

A struct containing: the identifier of the activity the room handle of the activity channel

In bindings that need a separate name, arrays of Activity should be called Activity_List.

Members

id − s
(undocumented)
room − u (Room_Handle)
(undocumented)

org.laptop.Telepathy.ActivityProperties

Implementations of this interface must also implement:

An interface on connections to associate OLPC activity properties with rooms.

The following types and names are used to request and set properties:

s:color
The color of the activity. Format used is #RRGGBB,#RRGGBB (stroke,fill).
s:name
The name of the activity.
s:type
The type of the activity.

Methods:

SetProperties ( u: room, a{sv}: properties ) → nothing

Set the properties of the activity associated to the given room for this connection. You have to be the owner of this activity.

Parameters

room − u
An integer handle representing the room of the activity
properties − a{sv}
A dictionary mapping properties names to the desired values

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)
org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)
org.freedesktop.Telepathy.Error.PermissionDenied
(Undocumented.)

GetProperties ( u: room ) → a{sv}

Get the properties of a particular activity.

Parameters

room − u
An integer handle for the activity's room to request his properties for

Returns

properties − a{sv}
A dictionary mapping properties names to their values

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)
org.freedesktop.Telepathy.Error.InvalidArgument
(Undocumented.)

Signals:

ActivityPropertiesChanged ( u: room, a{sv}: properties )

Signal emitted when the properties of an activity are changed.

Parameters

room − u
An integer handle representing the room of the activity
properties − a{sv}
A dictionary mapping properties names to their new values

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.laptop.Telepathy.Gadget

Implementations of this interface must also implement:

An interface on connections to interact with the Gadget component. Buddy and activity searches are performed by requesting BuddyView and ActivityView using the Connection.Interface.Requests interface.

Methods:

Publish ( b: publish ) → nothing

Publish your informations to Gadget so other users can search for you.

Parameters

publish − b
A boolean indicating if we want to publish your informations to Gadget.

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
(Undocumented.)

Signals:

GadgetDiscovered ( )

Signal emitted when CM discovers the Gadget component.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

GadgetAvailable − b, read-only

TRUE if the Gadget component was found on this connection.

org.laptop.Telepathy.Channel.Interface.View

Implementations of this interface must also implement:

An interface for channels representing the result of a Gadget search.

Buddy properties changes are notified on the Connection object using the BuddyInfo interface while the view object is alive.

Activity properties changes are notified on the Connection object using the ActivityProperties interface while the view object is alive.

Activities membership is notified on the Connection object using the BuddyInfo properties while the view object is alive.

Interface has no methods.

Signals:

ActivitiesChanged ( a(su): added, a(su): removed )

Signal emitted when the activities in the view are changed.

Parameters

added − a(su) (Activity[])
Room handles of the added activities
removed − a(su) (Activity[])
Room handles of the removed activities

BuddiesChanged ( au: added, au: removed )

Signal emitted when the buddies in the view are changed.

Parameters

added − au
Handles of the added buddies
removed − au
Handles of the removed buddies

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

MaxSize − u, read-only

The maximum number of elements that Gadget has to return to the search request.

When requesting a channel with Connection.Interface.Requests.CreateChannel, this property MUST be included in the request.

Buddies − au (Contact_Handle[]), read-only

The buddies who are in this view channel.

It does not make sense for this property to be in channel requests.

Activities − a(su) (Activity[]), read-only

The activities which are in this view channel.

It does not make sense for this property to be in channel requests.

org.laptop.Telepathy.Channel.Type.BuddyView

Implementations of this interface must also implement:

A channel used to search Buddies using Gadget.

The result of the search is available in the Buddies property of the channel. The Activities property should stay empty.

If no search criteria is defined then Gadget will return random buddies, up to the max size of the view channel.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Properties − a{sv}, read-only

If set when requesting the channel, Gadget will search for buddies having these properties.

Alias − s, read-only

If set when requesting the channel, Gadget will search for buddies having this alias.

org.laptop.Telepathy.Channel.Type.ActivityView

Implementations of this interface must also implement:

A channel used to search Activities using Gadget.

The result of the search is available in the Activities property and the participants of these activities are stored in the Buddies property of this channel.

If no search criteria is defined then Gadget will return random activities, up to the max size of the view channel.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Properties − a{sv}, read-only

If set when requesting the channel, Gadget will search for activities having these properties.

Participants − au, read-only

If set when requesting the channel, Gadget will search for activities in which the given buddies are participating.

Generic types

Types defined elsewhere

Room_Handle − u
Defined by: Telepathy specification
Contact_Handle − u
Defined by: Telepathy specification

Generic types

Types defined elsewhere

Contact_Handle − u
Defined by: Telepathy specification
DBus_Interface − s
Defined by: Telepathy specification
DBus_Qualified_Member − s
Defined by: Telepathy specification
Qualified_Property_Value_Map − a{sv}
Defined by: Telepathy specification

Index

Index of interfaces

Index of types