Presence Service D-Bus API: Difference between revisions
Jump to navigation
Jump to search
(Fill out bits of the PS API) |
No edit summary |
||
(80 intermediate revisions by 17 users not shown) | |||
Line 1: | Line 1: | ||
{{OLPC}} |
|||
=PresenceService DBus API= |
|||
=PresenceService D-Bus API= |
|||
There are 4 conceptual "objects": |
|||
<b>Revision 3 (post Collabora week)</b><br> |
|||
* PresenceService - manages and provides a query API for Buddy, Service, and Activity objects |
|||
There are 3 conceptual objects: |
|||
* PresenceService - manages and provides a query API for Activity and Buddy objects |
|||
* Activity - represents a shared space in which one or more buddies participate. Activities are globally unique. |
|||
* Buddy - represents another laptop somewhere on the network that you can communicate with |
* Buddy - represents another laptop somewhere on the network that you can communicate with |
||
* Service - represents some specific resource on the network, published by a buddy |
|||
* Activity - represents a logical collection of services, in which one or more buddies participate |
|||
==PresenceService Object== |
==PresenceService Object== |
||
Service: org.laptop.Sugar.Presence<br> |
|||
Signals (unfiltered, all events propogated): |
|||
Object Path: /org/laptop/Sugar/Presence<br> |
|||
* buddyAppeared (buddy object path) |
|||
* buddyDisappeared (buddy object path) |
|||
* serviceAppeared (service object path) |
|||
* serviceDisappeared (service object path) |
|||
* activityAppeared (activity object path) |
|||
* activityDisappeared (activity object path) |
|||
===org.laptop.Sugar.Presence=== |
|||
Methods: |
|||
* getAllServices() |
|||
====Signals==== |
|||
** Gets all services the PS knows about |
|||
* ActivityAppeared (o: activity) |
|||
** Returns: array of service object paths |
|||
** PS has become aware of the given activity, either because of an invitation (in which case the ActivityInvitation signal will follow soon after) or because someone is advertising it as public |
|||
* getAllServicesOfType(type) |
|||
* ActivityDisappeared (o: buddy) |
|||
** Gets all services the PS knows about, filtered by a specific service type |
|||
** PS believes that the given activity has disappeared - it is not advertised as public, and either nobody has sent us a private invitation, or everyone who invited us to it has gone offline |
|||
** Returns: array of service object paths |
|||
* BuddyAppeared (o: buddy) |
|||
* getAllActivities() |
|||
* BuddyDisappeared (o: buddy) |
|||
* ActivityInvitation (o: activity) |
|||
** The user has been invited to a (public or hidden) activity, represented by the given object (which might have been created immediately before). |
|||
** FIXME: as of 2007-08-28 this was documented to have parameters (o: activity, o: buddy), but the actual implementation only had one parameter? |
|||
* PrivateInvitation (s: bus_name, o: connection, o: channel) |
|||
** Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.) |
|||
====Methods==== |
|||
* GetActivities() -> ao |
|||
** Gets all activities the PS knows about |
** Gets all activities the PS knows about |
||
** Returns: array of activity object paths |
** Returns: array of activity object paths |
||
* getActivity(id) |
|||
* GetActivityById(s: id) -> o |
|||
** Gets a specific activity |
|||
** Gets a specific activity object by the activity's ID |
|||
** Returns: activity object path |
** Returns: activity object path |
||
* getAllBuddies() |
|||
* GetBuddies() -> ao |
|||
** Gets all buddies the PS knows about |
** Gets all buddies the PS knows about |
||
** Returns: array of buddy object paths |
** Returns: array of buddy object paths |
||
* getBuddyByName(name) |
|||
* GetBuddyByPublicKey(ay: key) -> o |
|||
** Gets a specific buddy, searching on the buddy's name |
|||
** |
** Gets a specific buddy, searching on the buddy's public key |
||
** Returns: the buddy object path of the requested buddy |
|||
* getBuddyByAddress(address) |
|||
** Gets a specific buddy, searching on the buddy's IP address |
|||
* GetBuddyByTelepathyHandle(sou) -> o |
|||
** Returns: the buddy object path of the requested buddy, or an error if the buddy does not exist |
|||
** Get the buddy corresponding to a Telepathy handle |
|||
* getOwner() |
|||
** Parameters: |
|||
** Gets the owner buddy, representing the owner of this laptop |
|||
*** conn_name: The well-known bus name of a Telepathy connection |
|||
** Returns: the buddy object path of the owner (always present) |
|||
*** conn_path: The object path of the Telepathy connection |
|||
*** handle: The handle of a Telepathy contact on that connection, of type HANDLE_TYPE_CONTACT. This may not be a channel-specific handle |
|||
** Returns: the object path of a Buddy |
|||
* GetOwner() -> o |
|||
** Gets the owner buddy object, which is always present |
|||
** Returns: the buddy object path of the owner |
|||
* ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o |
|||
** Shares an activity with others |
|||
** As of the Trial-2 API, the activity is visible to everyone; in the Trial-3 API it will be private by default |
|||
** Returns: object path representing the new activity |
|||
* GetPreferredConnection() -> so |
|||
** Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy. |
|||
** Returns: |
|||
*** bus name of the Telepathy connection |
|||
*** object path of the Telepathy connection |
|||
==Activity Object== |
|||
Object Path: /org/laptop/Sugar/Presence/Activities/<br> |
|||
===org.laptop.Sugar.Presence.Activity=== |
|||
====Signals==== |
|||
* ''BuddyJoined (o: buddy) - deprecated, see BuddyHandleJoined'' |
|||
* BuddyHandleJoined (o: buddy, u: handle) |
|||
* BuddyLeft (o: buddy) |
|||
* NewChannel (o: Telepathy channel) |
|||
* PropertiesChanged (a{sv}: changed properties) |
|||
** Unchanged properties are not mentioned in the dictionary |
|||
====Methods==== |
|||
* GetId() -> s |
|||
** Gets the activity's ID. Deprecated, use GetProperties() in new code |
|||
** Returns: string representing the activity's ID |
|||
* GetColor() -> s |
|||
** Gets the activity's color. Deprecated, use GetProperties() in new code |
|||
** Returns: the activity's color in string format |
|||
* GetName() -> s |
|||
** Gets the activity's name. Deprecated, use GetProperties() in new code |
|||
** Returns: the activity's name |
|||
* GetProperties() -> a{sv} |
|||
** Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are: |
|||
*** b: private (if False, advertised to all) |
|||
*** s: name (title or empty string if unknown) |
|||
*** s: tags (tags in some format chosen by the UI, initially empty string) |
|||
*** s: color (#112233,#456789 or empty string if unknown) |
|||
*** s: type (D-Bus well-known name) |
|||
*** s: id (activity ID) |
|||
* SetProperties(a{sv}) -> nothing |
|||
** Set the properties, which are as defined by GetProperties. Unchanged properties may be omitted. The type and ID cannot be changed. |
|||
* Join() -> nothing |
|||
** Joins the activity |
|||
** Returns: nothing, or an exception on error |
|||
* Invite(o: buddy, s: message) -> nothing |
|||
** Invites the buddy, sending the message with the invitation |
|||
** Raises NotJoined, NotFound, WrongConnection or a Telepathy error on failure |
|||
* GetJoinedBuddies() -> ao |
|||
** Gets all buddies who are currently participating in this activity |
|||
** Returns: array of buddy object paths |
|||
* GetChannels() -> soao |
|||
** Gets all the Telepathy channels (chat, tube, voip, etc) belonging to this activity |
|||
** Returns: |
|||
*** bus name of the Telepathy connection |
|||
*** object path of the Telepathy connection |
|||
*** array of Telepathy channel object paths |
|||
* ListChannels() -> soa(osuu) |
|||
** added in PS 0.81.3 (joyride-2128, 8.2-3) |
|||
** Return all the existing channels associated with this activity |
|||
** Returns: |
|||
*** the D-Bus well-known service name of the connection |
|||
*** the D-Bus object path of the connection |
|||
*** a list of tuples containing for each channel associated with this activity: |
|||
**** a D-Bus object path for the channel object |
|||
**** a D-Bus interface name representing the channel type |
|||
**** an integer representing the handle type this channel communicates with, or zero |
|||
**** an integer handle representing the contact, room or list this channel communicates with, or zero |
|||
==Buddy Object== |
|||
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
|||
===org.laptop.Sugar.Presence.Buddy=== |
|||
====Signals==== |
|||
Refered objects passed in signals are specific to this buddy only. |
|||
* IconChanged (ay: icon data) |
|||
* JoinedActivity (o: activity) |
|||
* LeftActivity (o: activity) |
|||
* PropertyChanged (a{sv}: changed) |
|||
====Methods==== |
|||
* GetProperties() -> a{sv} |
|||
** Gets all the general properties of the buddy |
|||
** Returns: a dbus dict of buddy properties, like nickname, realname, IP address, whether or not this buddy is the laptop owner, etc |
|||
* GetIcon() -> ay |
|||
** Gets the buddy's icon data |
|||
** Returns: a character array containing the byte stream of the icon data |
|||
* GetJoinedActivities() -> ao |
|||
** Gets all activities in which this buddy is currently participating |
|||
** Returns: array of activity object paths |
|||
==Owner Object== |
|||
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
|||
Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon. |
|||
===org.laptop.Sugar.Presence.Buddy.Owner=== |
|||
====Methods==== |
|||
* SetIcon(ay: data) |
|||
** Sets the buddy's icon data |
|||
** Returns: |
|||
* SetProperties(a{sv}: properties) -> nothing |
|||
** Sets various properties of the buddy, like nick name, color, and current activity |
|||
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid |
|||
[[Category:Sugar]] |
|||
[[Category:API]] |
|||
[[Category:Telepathy]] |
|||
[[Category:Collaboration]] |
Latest revision as of 16:30, 22 October 2008
This page is monitored by the OLPC team.
PresenceService D-Bus API
Revision 3 (post Collabora week)
There are 3 conceptual objects:
- PresenceService - manages and provides a query API for Activity and Buddy objects
- Activity - represents a shared space in which one or more buddies participate. Activities are globally unique.
- Buddy - represents another laptop somewhere on the network that you can communicate with
PresenceService Object
Service: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence
org.laptop.Sugar.Presence
Signals
- ActivityAppeared (o: activity)
- PS has become aware of the given activity, either because of an invitation (in which case the ActivityInvitation signal will follow soon after) or because someone is advertising it as public
- ActivityDisappeared (o: buddy)
- PS believes that the given activity has disappeared - it is not advertised as public, and either nobody has sent us a private invitation, or everyone who invited us to it has gone offline
- BuddyAppeared (o: buddy)
- BuddyDisappeared (o: buddy)
- ActivityInvitation (o: activity)
- The user has been invited to a (public or hidden) activity, represented by the given object (which might have been created immediately before).
- FIXME: as of 2007-08-28 this was documented to have parameters (o: activity, o: buddy), but the actual implementation only had one parameter?
- PrivateInvitation (s: bus_name, o: connection, o: channel)
- Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.)
Methods
- GetActivities() -> ao
- Gets all activities the PS knows about
- Returns: array of activity object paths
- GetActivityById(s: id) -> o
- Gets a specific activity object by the activity's ID
- Returns: activity object path
- GetBuddies() -> ao
- Gets all buddies the PS knows about
- Returns: array of buddy object paths
- GetBuddyByPublicKey(ay: key) -> o
- Gets a specific buddy, searching on the buddy's public key
- Returns: the buddy object path of the requested buddy
- GetBuddyByTelepathyHandle(sou) -> o
- Get the buddy corresponding to a Telepathy handle
- Parameters:
- conn_name: The well-known bus name of a Telepathy connection
- conn_path: The object path of the Telepathy connection
- handle: The handle of a Telepathy contact on that connection, of type HANDLE_TYPE_CONTACT. This may not be a channel-specific handle
- Returns: the object path of a Buddy
- GetOwner() -> o
- Gets the owner buddy object, which is always present
- Returns: the buddy object path of the owner
- ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o
- Shares an activity with others
- As of the Trial-2 API, the activity is visible to everyone; in the Trial-3 API it will be private by default
- Returns: object path representing the new activity
- GetPreferredConnection() -> so
- Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy.
- Returns:
- bus name of the Telepathy connection
- object path of the Telepathy connection
Activity Object
Object Path: /org/laptop/Sugar/Presence/Activities/
org.laptop.Sugar.Presence.Activity
Signals
- BuddyJoined (o: buddy) - deprecated, see BuddyHandleJoined
- BuddyHandleJoined (o: buddy, u: handle)
- BuddyLeft (o: buddy)
- NewChannel (o: Telepathy channel)
- PropertiesChanged (a{sv}: changed properties)
- Unchanged properties are not mentioned in the dictionary
Methods
- GetId() -> s
- Gets the activity's ID. Deprecated, use GetProperties() in new code
- Returns: string representing the activity's ID
- GetColor() -> s
- Gets the activity's color. Deprecated, use GetProperties() in new code
- Returns: the activity's color in string format
- GetName() -> s
- Gets the activity's name. Deprecated, use GetProperties() in new code
- Returns: the activity's name
- GetProperties() -> a{sv}
- Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are:
- b: private (if False, advertised to all)
- s: name (title or empty string if unknown)
- s: tags (tags in some format chosen by the UI, initially empty string)
- s: color (#112233,#456789 or empty string if unknown)
- s: type (D-Bus well-known name)
- s: id (activity ID)
- Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are:
- SetProperties(a{sv}) -> nothing
- Set the properties, which are as defined by GetProperties. Unchanged properties may be omitted. The type and ID cannot be changed.
- Join() -> nothing
- Joins the activity
- Returns: nothing, or an exception on error
- Invite(o: buddy, s: message) -> nothing
- Invites the buddy, sending the message with the invitation
- Raises NotJoined, NotFound, WrongConnection or a Telepathy error on failure
- GetJoinedBuddies() -> ao
- Gets all buddies who are currently participating in this activity
- Returns: array of buddy object paths
- GetChannels() -> soao
- Gets all the Telepathy channels (chat, tube, voip, etc) belonging to this activity
- Returns:
- bus name of the Telepathy connection
- object path of the Telepathy connection
- array of Telepathy channel object paths
- ListChannels() -> soa(osuu)
- added in PS 0.81.3 (joyride-2128, 8.2-3)
- Return all the existing channels associated with this activity
- Returns:
- the D-Bus well-known service name of the connection
- the D-Bus object path of the connection
- a list of tuples containing for each channel associated with this activity:
- a D-Bus object path for the channel object
- a D-Bus interface name representing the channel type
- an integer representing the handle type this channel communicates with, or zero
- an integer handle representing the contact, room or list this channel communicates with, or zero
Buddy Object
Object Path: /org/laptop/Sugar/Presence/Buddies/
org.laptop.Sugar.Presence.Buddy
Signals
Refered objects passed in signals are specific to this buddy only.
- IconChanged (ay: icon data)
- JoinedActivity (o: activity)
- LeftActivity (o: activity)
- PropertyChanged (a{sv}: changed)
Methods
- GetProperties() -> a{sv}
- Gets all the general properties of the buddy
- Returns: a dbus dict of buddy properties, like nickname, realname, IP address, whether or not this buddy is the laptop owner, etc
- GetIcon() -> ay
- Gets the buddy's icon data
- Returns: a character array containing the byte stream of the icon data
- GetJoinedActivities() -> ao
- Gets all activities in which this buddy is currently participating
- Returns: array of activity object paths
Owner Object
Object Path: /org/laptop/Sugar/Presence/Buddies/
Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon.
org.laptop.Sugar.Presence.Buddy.Owner
Methods
- SetIcon(ay: data)
- Sets the buddy's icon data
- Returns:
- SetProperties(a{sv}: properties) -> nothing
- Sets various properties of the buddy, like nick name, color, and current activity
- Returns: InvalidPropertyError if a property is unrecognized its value is invalid