Presence Service D-Bus API: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Studly-Cap signal names)
No edit summary
 
(68 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. Activities are globally unique.


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


===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