Presence Service D-Bus API: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Document that ShareActivity() will be private-by-default for Trial-3)
No edit summary
 
(32 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{OLPC}}
{{OLPC}}
=PresenceService DBus API=
=PresenceService D-Bus API=
<b>Revision 3 (post Collabora week)</b><br>
<b>Revision 3 (post Collabora week)</b><br>


Line 10: Line 10:
==PresenceService Object==
==PresenceService Object==
Service: org.laptop.Sugar.Presence<br>
Service: org.laptop.Sugar.Presence<br>
Interface: org.laptop.Sugar.Presence<br>
Object Path: /org/laptop/Sugar/Presence<br>
Object Path: /org/laptop/Sugar/Presence<br>


===org.laptop.Sugar.Presence===
===Signals===

====Signals====
* ActivityAppeared (o: activity)
* 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
** 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
Line 26: Line 27:
** Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.)
** Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.)


===Methods===
====Methods====
* GetActivities() -> ao
* 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

* GetActivityById(s: id) -> o
* GetActivityById(s: id) -> o
** Gets a specific activity object by the activity's ID
** Gets a specific activity object by the activity's ID
** Returns: activity object path
** Returns: activity object path

* GetBuddies() -> ao
* 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

* GetBuddyByPublicKey(ay: key) -> o
* GetBuddyByPublicKey(ay: key) -> o
** Gets a specific buddy, searching on the buddy's public key
** Gets a specific buddy, searching on the buddy's public key
** Returns: the buddy object path of the requested buddy
** 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
* GetOwner() -> o
** Gets the owner buddy object, which is always present
** Gets the owner buddy object, which is always present
** Returns: the buddy object path of the owner
** Returns: the buddy object path of the owner

* ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o
* ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o
** Shares an activity with others
** 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
** 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
** Returns: object path representing the new activity

* GetPreferredConnection() -> so
* GetPreferredConnection() -> so
** Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy.
** Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy.
Line 53: Line 68:


==Activity Object==
==Activity Object==
Interface: org.laptop.Sugar.Presence.Activity<br>
Object Path: /org/laptop/Sugar/Presence/Activities/<br>
Object Path: /org/laptop/Sugar/Presence/Activities/<br>


===org.laptop.Sugar.Presence.Activity===
===Signals===
====Signals====
* BuddyJoined (o: buddy)
* ''BuddyJoined (o: buddy) - deprecated, see BuddyHandleJoined''
* BuddyHandleJoined (o: buddy, u: handle)
* BuddyLeft (o: buddy)
* BuddyLeft (o: buddy)
* NewChannel (o: Telepathy channel)
* NewChannel (o: Telepathy channel)
* PropertiesChanged (a{sv}: changed properties)
** Unchanged properties are not mentioned in the dictionary


===Methods===
====Methods====
* GetId() -> s
* 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
* GetColor() -> s
** Gets the activity's color
** Gets the activity's color. Deprecated, use GetProperties() in new code
** Returns: the activity's color in string format
** Returns: the activity's color in string format
* GetName() -> s
* GetName() -> s
** Gets the activity's name
** Gets the activity's name. Deprecated, use GetProperties() in new code
** Returns: the activity's name
** Returns: the activity's name
* GetType() -> s
* GetProperties() -> a{sv}
** Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are:
** Gets the activity's type
*** b: private (if False, advertised to all)
** Returns: the activity's type
*** 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
* Join() -> nothing
** Joins the activity
** Joins the activity
** Returns: nothing, or an exception on error
** 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
* GetJoinedBuddies() -> ao
** Gets all buddies who are currently participating in this activity
** Gets all buddies who are currently participating in this activity
Line 86: Line 114:
*** object path of the Telepathy connection
*** object path of the Telepathy connection
*** array of Telepathy channel object paths
*** 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==
Interface: org.laptop.Sugar.Presence.Buddy<br>
Object Path: /org/laptop/Sugar/Presence/Buddies/<br>
Object Path: /org/laptop/Sugar/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 (ay: icon data)
* IconChanged (ay: icon data)
Line 98: Line 138:
* PropertyChanged (a{sv}: changed)
* PropertyChanged (a{sv}: changed)


===Methods===
====Methods====
* GetProperties() -> a{sv}
* GetProperties() -> a{sv}
** Gets all the general properties of the buddy
** Gets all the general properties of the buddy
Line 110: Line 150:


==Owner Object==
==Owner Object==
Interface: org.laptop.Sugar.Presence.Buddy.Owner<br>
Object Path: /org/laptop/Sugar/Presence/Buddies/<br>
Object Path: /org/laptop/Sugar/Presence/Buddies/<br>


Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon.
Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon.


===org.laptop.Sugar.Presence.Buddy.Owner===
===Methods===
====Methods====
* SetIcon(ay: data)
* SetIcon(ay: data)
** Sets the buddy's icon data
** Sets the buddy's icon data
Line 123: Line 163:
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid


[[Category:Sugar]]

[[Category:Sugar]] [[Category:API]]
[[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)
  • 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