Presence Service D-Bus API: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Update some function names and add interfaces for Service, Buddy, and Activity)
No edit summary
 
(70 intermediate revisions by 16 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. A service may belong to either one activity or none; but never more than one activity.
* Activity - represents a logical collection of services, in which one or more buddies participate


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


===org.laptop.Sugar.Presence===
===Signals===
* buddyAppeared (buddy object path)
* buddyDisappeared (buddy object path)
* serviceAppeared (service object path)
* serviceDisappeared (service object path)
* activityAppeared (activity object path)
* activityDisappeared (activity object path)


===Methods===
====Signals====
* ActivityAppeared (o: activity)
* getServices()
** 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
** Gets all services the PS knows about
* ActivityDisappeared (o: buddy)
** Returns: array of service object paths
** 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
* getServicesOfType(type)
* BuddyAppeared (o: buddy)
** Gets all services the PS knows about, filtered by a specific service type
* BuddyDisappeared (o: buddy)
** Returns: array of service object paths
* ActivityInvitation (o: activity)
* getActivities()
** 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)
* GetBuddyByPublicKey(ay: key) -> o
** 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
** 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
* shareActivity(activityId, serviceType, properties, address, port, domain)
*** handle: The handle of a Telepathy contact on that connection, of type HANDLE_TYPE_CONTACT. This may not be a channel-specific handle
** Announces an activity on the network
** Returns: service object path representing the new share service for this activity
** Returns: the object path of a Buddy

* joinActivity(activity object path, serviceType)
* GetOwner() -> o
** given a known activity and activity's flagship service type, announce that this laptop has joined a particular activity
** Gets the owner buddy object, which is always present
** Returns: success or failure as a boolean
** Returns: the buddy object path of the owner
* 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.
* ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o
** Returns: service object path representing the new service
** 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==
==Buddy Object==
Interface: org.laptop.Presence.Buddy<br>
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 (ay: icon data)
* iconChanged ()
* 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)


===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()
* GetIcon() -> ay
** Gets the buddy's icon pixbuf data
** 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


==Service Object==
==Owner Object==
Interface: org.laptop.Presence.Service<br>
Object Path: /org/laptop/Sugar/Presence/Buddies/<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===
(none)
===Methods===
* getProperties()
** Gets all the service's properties
** Returns: a dbus dict of properties (name, type, activityId, port, published address, source address, domain)
* getPublishedValue(key)
** Gets a single value from the service's advertisement's DNS TXT record
** Returns: the value as a dbus string


===org.laptop.Sugar.Presence.Buddy.Owner===
==Activity Object==
====Methods====
Interface: org.laptop.Presence.Activity<br>
* SetIcon(ay: data)
Object Path: /org/laptop/Presence/Activities/<br>
** Sets the buddy's icon data

** Returns:
===Signals===
* SetProperties(a{sv}: properties) -> nothing
* buddyJoined (buddy object path)
** Sets various properties of the buddy, like nick name, color, and current activity
* buddyLeft (buddy object path)
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid
* serviceAppeared (service object path)
* serviceDisappeared (service object path)


[[Category:Sugar]]
===Methods===
[[Category:API]]
* getId()
[[Category:Telepathy]]
** Gets the activity's ID
[[Category:Collaboration]]
** Returns: string representing the activity's ID
* ownerHasJoined()
** Returns whether or not the owner has joined this activity
** Returns: boolean
* getServices()
** Gets all services that exist within the scope of this activity
** Returns: array of service object paths
* getServicesOfType(type)
** Gets all services of a specified type that exist within the scope of this activity
** Returns: array of service object paths
* getJoinedBuddies()
** Gets all buddies who are currently participating in this activity
** Returns: array of buddy object paths

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