Presence Service D-Bus API: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
(63 intermediate revisions by 14 users not shown) | |||
Line 1: | Line 1: | ||
{{OLPC}} |
{{OLPC}} |
||
=PresenceService |
=PresenceService D-Bus API= |
||
<b>Revision |
<b>Revision 3 (post Collabora week)</b><br> |
||
There are |
There are 3 conceptual objects: |
||
* PresenceService - manages and provides a query API for Activity |
* PresenceService - manages and provides a query API for Activity and Buddy objects |
||
* Activity - represents a |
* 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 |
||
* Channel - the logical communication mechanism between buddies participating in an Activity. Each Channel exists within the context of an Activity. |
|||
* Service - represents some specific resource on the network, published by a buddy. A service may belong to either one activity or none; but never more than one activity. |
|||
==PresenceService Object== |
==PresenceService Object== |
||
Service: org.laptop.Presence<br> |
Service: org.laptop.Sugar.Presence<br> |
||
Object Path: /org/laptop/Sugar/Presence<br> |
|||
Object Path: /org/laptop/Presence<br> |
|||
===org.laptop.Sugar.Presence=== |
|||
===Signals=== |
|||
* ActivityAppeared (activity object path) |
|||
* ActivityDisappeared (activity object path) |
|||
* BuddyAppeared (buddy object path) |
|||
* BuddyDisappeared (buddy object path) |
|||
* ServiceAppeared (service object path) |
|||
* ServiceDisappeared (service object path) |
|||
=== |
====Signals==== |
||
* ActivityAppeared (o: activity) |
|||
* getActivities() |
|||
** 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 |
** 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 |
||
* getBuddies() |
|||
* 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) |
|||
** Gets a specific buddy, searching on the buddy's name |
|||
** Returns: the buddy object path of the requested buddy, or an error if the buddy does not exist |
|||
* getBuddyByAddress(address) |
|||
** Gets a specific buddy, searching on the buddy's IP address |
|||
** Returns: the buddy object path of the requested buddy, or an error if the buddy does not exist |
|||
* getOwner() |
|||
** Gets the owner buddy, representing the owner of this laptop |
|||
** Returns: the buddy object path of the owner (always present) |
|||
* shareActivity(activityId, serviceType, properties, address, port, domain) |
|||
** Announces an activity on the network |
|||
** Returns: service object path representing the new share service for this activity |
|||
* joinActivity(activity object path, serviceType) |
|||
** given a known activity and activity's flagship service type, announce that this laptop has joined a particular activity |
|||
** Returns: success or failure as a boolean |
|||
* getServices() |
|||
** Gets all services the PS knows about |
|||
** Returns: array of service object paths |
|||
* getServicesOfType(type) |
|||
** Gets all services the PS knows about, filtered by a specific service type |
|||
** Returns: array of service object paths |
|||
* registerService(name, serviceType, properties, address, port, domain) |
|||
** Announces the availability of a non-Activity-related service. Low level and should not generally be used unless really needed. |
|||
** Returns: service object path representing the new service |
|||
* unregisterService(service object path) |
|||
** Unregisters the non-Activity-related service, notifying others that this service is no longer provided by this laptop. Low level and should not generally be used unless really needed. |
|||
** Returns: nothing |
|||
* 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== |
==Activity Object== |
||
Object Path: /org/laptop/Sugar/Presence/Activities/<br> |
|||
Object Path: /org/laptop/Presence/Activities/<br> |
|||
===org.laptop.Sugar.Presence.Activity=== |
|||
===Signals=== |
|||
====Signals==== |
|||
* BuddyJoined (buddy object path) |
|||
* ''BuddyJoined (o: buddy) - deprecated, see BuddyHandleJoined'' |
|||
* BuddyLeft (buddy object path) |
|||
* BuddyHandleJoined (o: buddy, u: handle) |
|||
* ServiceAppeared (service object path) |
|||
* BuddyLeft (o: buddy) |
|||
* ServiceDisappeared (service object path) |
|||
* NewChannel (o: Telepathy channel) |
|||
* PropertiesChanged (a{sv}: changed properties) |
|||
** Unchanged properties are not mentioned in the dictionary |
|||
===Methods=== |
====Methods==== |
||
* |
* GetId() -> s |
||
** Gets the activity's ID |
** Gets the activity's ID. Deprecated, use GetProperties() in new code |
||
** Returns: string representing the activity's ID |
** Returns: string representing the activity's ID |
||
* GetColor() -> s |
|||
* ownerHasJoined() |
|||
** Gets the activity's color. Deprecated, use GetProperties() in new code |
|||
** Returns whether or not the owner has joined this activity |
|||
** Returns: |
** Returns: the activity's color in string format |
||
* GetName() -> s |
|||
* getServices() |
|||
** Gets the activity's name. Deprecated, use GetProperties() in new code |
|||
** Gets all services that exist within the scope of this activity |
|||
** Returns: |
** Returns: the activity's name |
||
* GetProperties() -> a{sv} |
|||
* getServicesOfType(type) |
|||
** Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are: |
|||
** Gets all services of a specified type that exist within the scope of this activity |
|||
*** b: private (if False, advertised to all) |
|||
** Returns: array of service object paths |
|||
*** s: name (title or empty string if unknown) |
|||
* getJoinedBuddies() |
|||
*** 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 |
** Gets all buddies who are currently participating in this activity |
||
** Returns: array of buddy object paths |
** 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== |
==Buddy Object== |
||
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
|||
Object Path: /org/laptop/Presence/Buddies/<br> |
|||
===org.laptop.Sugar.Presence.Buddy=== |
|||
===Signals=== |
|||
====Signals==== |
|||
Refered objects passed in signals are specific to this buddy only. |
Refered objects passed in signals are specific to this buddy only. |
||
* IconChanged () |
* IconChanged (ay: icon data) |
||
* JoinedActivity (o: activity) |
|||
* ServiceAppeared (service object path) |
|||
* LeftActivity (o: activity) |
|||
* ServiceDisappeared (service object path) |
|||
* PropertyChanged (a{sv}: changed) |
|||
* JoinedActivity (activity object path) |
|||
* LeftActivity (activity object path) |
|||
* PropertyChanged (list of property names) |
|||
===Methods=== |
====Methods==== |
||
* GetProperties() -> a{sv} |
|||
* getProperties() |
|||
** Gets all the general properties of the buddy |
** 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 |
** 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 |
** Gets the buddy's icon data |
||
** Returns: a character array containing the byte stream of the icon data |
** Returns: a character array containing the byte stream of the icon data |
||
* GetJoinedActivities() -> ao |
|||
* getServiceOfType(type) |
|||
** Gets one service of a specific type. Services must be unique within an activity, and can be "belong" to either one activity or none; but never more than one. |
|||
** Returns: service object path, or error if no service of the requested type existed |
|||
* getJoinedActivities() |
|||
** Gets all activities in which this buddy is currently participating |
** Gets all activities in which this buddy is currently participating |
||
** Returns: array of activity object paths |
** Returns: array of activity object paths |
||
== |
==Owner Object== |
||
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
|||
Object Path: /org/laptop/Presence/Channel/<br> |
|||
===Signals=== |
|||
* BuddyAppeared (buddy object path) |
|||
* BuddyDisappeared (buddy object path) |
|||
===Methods=== |
|||
* getType() |
|||
** Gets the channel's type. Only one Channel of each type may exist within an activity at any given time. Messages sent to the Channel are sent to each Buddy on the Channel, and each message sent to the Channel is received by each Buddy on the Channel. The Channel is conceptually a one-to-many communications pipe. It should be assumed that every Buddy that participates in an activity is "on" every Channel the activity provides. |
|||
** Returns: a string representing the channel's type |
|||
* getBuddies() |
|||
** Gets all buddies on the channel |
|||
** Returns: array of buddy object paths |
|||
==Service Object== |
|||
Interface: org.laptop.Presence.Service<br> |
|||
Object Path: /org/laptop/Presence/Services/<br> |
|||
Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon. |
|||
===Signals=== |
|||
* PropertyChanged (list of property names) |
|||
===org.laptop.Sugar.Presence.Buddy.Owner=== |
|||
===Methods=== |
|||
====Methods==== |
|||
* getProperties() |
|||
* SetIcon(ay: data) |
|||
** Gets all the service's properties |
|||
** Sets the buddy's icon data |
|||
** Returns: a dbus dict of properties (name, type, activityId, port, published address, source address, domain) |
|||
** Returns: |
|||
* getPublishedValue(key) |
|||
* SetProperties(a{sv}: properties) -> nothing |
|||
** Gets a single value from the service's advertisement's DNS TXT record |
|||
** Sets various properties of the buddy, like nick name, color, and current activity |
|||
** Returns: the value as a dbus string |
|||
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid |
|||
[[Category:Sugar]] |
[[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