[Telepathy-commits] [telepathy-gabble/master] Location: add spec Connection.Interface.Presence in extensions/ for Rich_Presence_Access_Control_Type
Alban Crequy
alban.crequy at collabora.co.uk
Sun Feb 1 05:23:58 PST 2009
---
extensions/Connection_Interface_Presence.xml | 448 ++++++++++++++++++++++++++
extensions/Makefile.am | 1 +
extensions/all.xml | 17 +
3 files changed, 466 insertions(+), 0 deletions(-)
create mode 100644 extensions/Connection_Interface_Presence.xml
diff --git a/extensions/Connection_Interface_Presence.xml b/extensions/Connection_Interface_Presence.xml
new file mode 100644
index 0000000..8ec9a76
--- /dev/null
+++ b/extensions/Connection_Interface_Presence.xml
@@ -0,0 +1,448 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>
+ Copyright (C) 2005, 2006 Collabora Limited
+ </tp:copyright>
+ <tp:copyright>
+Copyright (C) 2005, 2006 Nokia Corporation
+ </tp:copyright>
+ <tp:copyright>
+Copyright (C) 2006 INdT
+ </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <!-- We hope to simplify these eventually -->
+ <tp:mapping name="Multiple_Status_Map">
+ <tp:docstring>Mapping used in Last_Activity_And_Statuses and passed to
+ SetStatus, representing a collection of statuses. Use of this mapping
+ with more than one member is deprecated.</tp:docstring>
+ <tp:member type="s" name="Status"/>
+ <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/>
+ </tp:mapping>
+ <tp:struct name="Last_Activity_And_Statuses" array-name="">
+ <tp:docstring>Structure representing a contact's presence, containing
+ a last-activity time (deprecated) and a Multiple_Status_Map.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Unix_Timestamp" name="Last_Activity"/>
+ <tp:member type="a{sa{sv}}" tp:type="Multiple_Status_Map"
+ name="Statuses"/>
+ </tp:struct>
+ <tp:mapping name="Contact_Presences">
+ <tp:docstring>Mapping returned by GetPresence and signalled by
+ PresenceUpdate, where the keys are contacts and the values represent
+ their presences.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Contact"/>
+ <tp:member type="(ua{sa{sv}})" tp:type="Last_Activity_And_Statuses"
+ name="Presence"/>
+ </tp:mapping>
+ <tp:struct name="Status_Spec" array-name="">
+ <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"/>
+ <tp:member type="b" name="May_Set_On_Self"/>
+ <tp:member type="b" name="Exclusive"/>
+ <tp:member type="a{ss}" tp:type="String_String_Map"
+ name="Parameter_Types"/>
+ </tp:struct>
+ <tp:mapping name="Status_Spec_Map">
+ <tp:member type="s" name="Identifier"/>
+ <tp:member type="(ubba{ss})" tp:type="Status_Spec" name="Spec"/>
+ </tp:mapping>
+
+ <method name="AddStatus" tp:name-for-bindings="Add_Status">
+ <arg direction="in" name="Status" type="s">
+ <tp:docstring>
+ The string identifier of the desired status
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Parameters" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring>
+ A dictionary of optional parameter names mapped to their variant-boxed values
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that a single presence status is published for the user, along
+ with any desired parameters. Changes will be indicated by PresenceUpdate
+ signals being emitted.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <method name="ClearStatus" tp:name-for-bindings="Clear_Status">
+ <tp:docstring>
+ Request that all of a user's presence statuses be removed. Be aware
+ that this request may simply result in the statuses being replaced by a
+ default available status. Changes will be indicated by PresenceUpdate
+ signals being emitted.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <method name="GetPresence" tp:name-for-bindings="Get_Presence">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of the contacts whose presence should be obtained
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Presence" type="a{u(ua{sa{sv}})}"
+ tp:type="Contact_Presences">
+ <tp:docstring>
+ Presence information in the same format as for the PresenceUpdate
+ signal
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get presence previously emitted by PresenceUpdate for the given
+ contacts. Data is returned in the same structure as the PresenceUpdate
+ signal. Using this method in favour of RequestPresence has the
+ advantage that it will not wake up each client connected to the
+ PresenceUpdate signal.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+ <method name="GetStatuses" tp:name-for-bindings="Get_Statuses">
+ <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map">
+ <tp:docstring>
+ A dictionary of string identifiers mapped to a struct for each status, containing:
+ <ul>
+ <li>a type value from one of the values above</li>
+ <li>a boolean to indicate if this status may be set on yourself</li>
+ <li>a boolean to indicate if this is an exclusive status which you may not set alongside any other</li>
+ <li>a dictionary of valid optional string argument names mapped to their types</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get a dictionary of the valid presence statuses for this connection.
+ This is only available when online because only some statuses will
+ be available on some servers.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+ <signal name="PresenceUpdate" tp:name-for-bindings="Presence_Update">
+ <arg name="Presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences">
+ <tp:docstring>
+ A dictionary of contact handles mapped to a struct containing
+ a UNIX timestamp of the last activity time (in UTC), and
+ a dictionary mapping the contact's current status identifiers to
+ a dictionary of optional parameter names mapped to their
+ variant-boxed values
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ This signal should be emitted when your own presence has been changed,
+ or the presence of the member of any of the connection's channels has
+ been changed, or when the presence requested by RequestPresence is available.
+
+ </tp:docstring>
+ </signal>
+ <method name="RemoveStatus" tp:name-for-bindings="Remove_Status">
+ <arg direction="in" name="Status" type="s">
+ <tp:docstring>
+ The string identifier of the status not to publish anymore for the user
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the given presence status is no longer published for the
+ user. Changes will be indicated by PresenceUpdate signals being
+ emitted. As with ClearStatus, removing a status may actually result in
+ it being replaced by a default available status.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>The status requested is not currently set</tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ <method name="RequestPresence" tp:name-for-bindings="Request_Presence">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of the contacts whose presence should be obtained
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request the presence for contacts on this connection. A PresenceUpdate
+ signal will be emitted when they are received. This is not the same as
+ subscribing to the presence of a contact, which must be done using the
+ 'subscription' Channel.Type.ContactList, and on some protocols presence
+ information may not be available unless a subscription exists.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The presence of the requested contacts is not reported to this connection
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ <method name="SetLastActivityTime"
+ tp:name-for-bindings="Set_Last_Activity_Time">
+ <arg direction="in" name="Time" type="u" tp:type="Unix_Timestamp">
+ <tp:docstring>
+ A UNIX timestamp of the user's last activity time (in UTC)
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the recorded last activity time for the user be updated on
+ the server.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ This protocol has no concept of idle time
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ <method name="SetStatus" tp:name-for-bindings="Set_Status">
+ <arg direction="in" name="Statuses" type="a{sa{sv}}" tp:type="Multiple_Status_Map">
+ <tp:docstring>
+ A dictionary mapping status identifiers to dictionaries, which
+ map optional parameter names to their variant-boxed values
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the user's presence be changed to the given statuses and
+ desired parameters. Changes will be reflected by PresenceUpdate
+ signals being emitted. On certain protocols, this method may be
+ called on a newly-created connection which is still in the
+ DISCONNECTED state, and will sign on with the requested status.
+ If the requested status is not available after signing on,
+ NotAvailable will be returned and the connection will remain
+ offline, or if the protocol does not support signing on with
+ a certain status, Disconnected will be returned.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface will become deprecated in future versions. New
+ client implementations MAY use
+ org.freedesktop.Telepathy.Connection.Interface.SimplePresence
+ instead; new connection managers SHOULD implement both
+ Presence and SimplePresence.</p>
+
+ <p>This interface is for services which have a concept of presence which
+ can be published for yourself and monitored on your contacts.
+ Telepathy's definition of presence is based on that used by
+ <a href="http://www.galago-project.org/">the Galago
+ project</a>.</p>
+
+ <p>Presence on an individual (yourself or one of your contacts) is modelled as
+ a last activity time along with a set of zero or more statuses, each of
+ which may have arbitrary key/value parameters. Valid statuses are defined
+ per connection, and a list of them can be obtained with the GetStatuses
+ method.</p>
+
+ <p>Each status has an arbitrary string identifier which should have an agreed
+ meaning between the connection manager and any client which is expected to
+ make use of it. The following well-known values (in common with those in
+ Galago) should be used where possible to allow clients to identify common
+ choices:</p>
+
+ <ul>
+ <li>available (corresponding to Connection_Presence_Type_Available)</li>
+ <li>away (corresponding to Connection_Presence_Type_Away)</li>
+ <li>brb (Be Right Back) (corresponding to
+ Connection_Presence_Type_Away, but more specific)</li>
+ <li>busy (corresponding to Connection_Presence_Type_Busy)</li>
+ <li>dnd (Do Not Disturb) (corresponding to
+ Connection_Presence_Type_Busy, but more specific)</li>
+ <li>xa (Extended Away) (corresponding to
+ Connection_Presence_Type_Extended_Away)</li>
+ <li>hidden (aka Invisible) (corresponding to
+ Connection_Presence_Type_Hidden)</li>
+ <li>offline (corresponding to Connection_Presence_Type_Offline)</li>
+ <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li>
+ <li>error (corresponding to Connection_Presence_Type_Error)</li>
+ </ul>
+
+ <p>As well as these well-known status identifiers, every status also has a
+ numerical type value chosen from ConnectionPresenceType which can be
+ used by the client to classify even unknown statuses into different
+ fundamental types.</p>
+
+ <p>These numerical types exist so that even if a client does not understand
+ the string identifier being used, and hence cannot present the presence to
+ the user to set on themselves, it may display an approximation of the
+ presence if it is set on a contact.</p>
+
+ <p>The dictionary of variant types allows the connection manager to exchange
+ further protocol-specific information with the client. It is recommended
+ that the string (s) argument 'message' be interpreted as an optional
+ message which can be associated with a presence status.</p>
+
+ <p>If the connection has a 'subscribe' contact list, PresenceUpdate signals
+ should be emitted to indicate changes of contacts on this list, and should
+ also be emitted for changes in your own presence. Depending on the
+ protocol, the signal may also be emitted for others such as people with
+ whom you are communicating, and any user interface should be updated
+ accordingly.</p>
+
+ <p>On some protocols, RequestPresence may only succeed on contacts on your
+ 'subscribe' list, and other contacts will cause a PermissionDenied error.
+ On protocols where there is no 'subscribe' list, and RequestPresence
+ succeeds, a client may poll the server intermittently to update any display
+ of presence information.</p>
+ </tp:docstring>
+ <tp:enum name="Connection_Presence_Type" type="u">
+ <tp:enumvalue suffix="Unset" value="0">
+ <tp:docstring>
+ An invalid presence type used as a null value. This value MUST NOT
+ appear in the result of GetStatuses, or in the Statuses property
+ of the SimplePresence interface.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Offline" value="1">
+ <tp:docstring>
+ Offline
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Available" value="2">
+ <tp:docstring>
+ Available
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Away" value="3">
+ <tp:docstring>
+ Away
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Extended_Away" value="4">
+ <tp:docstring>
+ Away for an extended time
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Hidden" value="5">
+ <tp:docstring>
+ Hidden (invisible)
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Busy" value="6">
+ <tp:added version="0.17.0"/>
+ <tp:docstring>
+ Busy, Do Not Disturb.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Unknown" value="7">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Unknown, unable to determine presence for this contact, for example
+ if the protocol only allows presence of subscribed contacts.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Error" value="8">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Error, an error occurred while trying to determine presence. The
+ message, if set, is an error from the server.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Rich_Presence_Access_Control_Type" type="u">
+ <tp:docstring>
+ A type of access control for Rich_Presence_Access_Control.
+ For most types, the exact access control is given by an associated
+ variant.
+
+ <tp:rationale>
+ These are the access control types from XMPP publish/subscribe
+ (XEP-0060).
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Whitelist" value="0">
+ <tp:docstring>
+ The associated variant is a list of contacts (signature 'au',
+ Contact_Handle[]) who can see the extended presence information.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Publish_List" value="1">
+ <tp:docstring>
+ All contacts in the user's 'publish' contact list can see the
+ extended presence information. The associated variant is ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Group" value="2">
+ <tp:docstring>
+ The associated variant is a handle of type Group (signature 'u',
+ Group_Handle) representing a group of contacts who can see the
+ extended presence information.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Open" value="3">
+ <tp:docstring>
+ Anyone with access to the service can see the extended presence
+ information.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Rich_Presence_Access_Control">
+ <tp:docstring>
+ An access control mode for extended presence items like geolocation.
+ This type isn't actually used by the core Presence interface, but
+ it's included here so it can be referenced by other specifications.
+ </tp:docstring>
+
+ <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
+ <tp:docstring>
+ The type of access control to apply.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Detail" type="v">
+ <tp:docstring>
+ Any additional information required by the Type. The required
+ type and semantics are defined for each
+ Rich_Presence_Access_Control_Type.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Makefile.am b/extensions/Makefile.am
index 073abe4..8cfc44d 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -9,6 +9,7 @@ EXTRA_DIST = \
Channel_Type_DBus_Tube.xml \
Channel_Type_Stream_Tube.xml \
Connection_Interface_Location.xml \
+ Connection_Interface_Presence.xml \
OLPC_Activity_Properties.xml \
OLPC_Buddy_Info.xml \
OLPC_Gadget.xml \
diff --git a/extensions/all.xml b/extensions/all.xml
index d0779d5..56bd36d 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -34,6 +34,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
<xi:include href="Channel_Bundle.xml"/>
<xi:include href="Channel_Future.xml"/>
<xi:include href="Connection_Interface_Location.xml"/>
+<xi:include href="Connection_Interface_Presence.xml"/>
<xi:include href="OLPC_Buddy_Info.xml"/>
<xi:include href="OLPC_Activity_Properties.xml"/>
<xi:include href="OLPC_Gadget.xml"/>
@@ -59,6 +60,19 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
from="Telepathy specification"/>
<tp:external-type name="Qualified_Property_Value_Map" type="a{sv}"
from="Telepathy specification"/>
+
+ <!-- for localisation -->
+ <tp:external-type name="Rich_Presence_Access_Control_Type" type="u"
+ from="Telepathy specification"/>
+ <tp:external-type name="Rich_Presence_Access_Control" type="(uv)"
+ from="Telepathy specification"/>
+ <tp:external-type name="Unix_Timestamp64" type="t"
+ from="Telepathy specification"/>
+ <tp:external-type name="Unix_Timestamp" type="u"
+ from="Telepathy specification"/>
+ <tp:external-type name="String_String_Map" type="a{ss}"
+ from="Telepathy specification"/>
+
<tp:external-type name="String_Variant_Map" type="a{sv}"
from="Telepathy specification"/>
@@ -76,6 +90,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
<tp:external-type name="DBus_Tube_Member" type="(us)"
from="Telepathy specification"/>
+<<<<<<< HEAD:extensions/all.xml
<!-- use types from Connection_Interface_Contact_Capabilities -->
<tp:external-type name="Requestable_Channel_Class" type="(a{sv}as)"
from="Telepathy specification"/>
@@ -88,6 +103,8 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
<tp:external-type name="Unix_Timestamp" type="u"
from="Telepathy specification"/>
+=======
+>>>>>>> 68d5a39... Location: add spec Connection.Interface.Presence in extensions/ for Rich_Presence_Access_Control_Type:extensions/all.xml
</tp:generic-types>
</tp:spec>
--
1.5.6.5
More information about the Telepathy-commits
mailing list