[Telepathy-commits] [telepathy-spec/master] Presence: add cross-references
Will Thompson
will.thompson at collabora.co.uk
Fri Nov 21 11:46:22 PST 2008
---
spec/Connection_Interface_Presence.xml | 118 ++++++++++++++++++--------------
1 files changed, 66 insertions(+), 52 deletions(-)
diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 58ad34e..cfcb856 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -29,9 +29,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<!-- 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:docstring>Mapping used in
+ <tp:type>Last_Activity_And_Statuses</tp:type> and passed to
+ <tp:member-ref>SetStatus</tp:member-ref>, 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>
@@ -44,9 +46,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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:docstring>Mapping returned by
+ <tp:member-ref>GetPresence</tp:member-ref> and signalled by
+ <tp:member-ref>PresenceUpdate</tp:member-ref>, 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"/>
@@ -76,8 +79,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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.
+ with any desired parameters. Changes will be indicated by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -91,8 +94,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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.
+ default available status. Changes will be indicated by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -109,16 +112,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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
+ Presence information in the same format as for the
+ <tp:member-ref>PresenceUpdate</tp:member-ref> 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.
+ Get presence previously emitted by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> for the given contacts.
+ Data is returned in the same structure as the PresenceUpdate signal.
+ Using this method in favour of
+ <tp:member-ref>RequestPresence</tp:member-ref> 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"/>
@@ -133,8 +137,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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>
+ <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>
@@ -161,8 +167,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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.
-
+ been changed, or when the presence requested by
+ <tp:member-ref>RequestPresence</tp:member-ref> is available.
</tp:docstring>
</signal>
<method name="RemoveStatus" tp:name-for-bindings="Remove_Status">
@@ -173,9 +179,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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.
+ user. Changes will be indicated by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As
+ with <tp:member-ref>ClearStatus</tp:member-ref>, 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"/>
@@ -193,11 +200,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</arg>
<tp:docstring>
- Request the presence for contacts on this connection. A PresenceUpdate
+ Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref>
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.
+ 'subscription' <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>,
+ 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"/>
@@ -241,7 +250,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<tp:docstring>
Request that the user's presence be changed to the given statuses and
- desired parameters. Changes will be reflected by PresenceUpdate
+ desired parameters. Changes will be reflected by
+ <tp:member-ref>PresenceUpdate</tp:member-ref>
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.
@@ -260,22 +270,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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>
+ client implementations MAY use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ 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>
+ <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>
+ per connection, and a list of them can be obtained with the
+ <tp:member-ref>GetStatuses</tp:member-ref> 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
@@ -301,9 +310,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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>
+ numerical type value chosen from
+ <tp:type>Connection_Presence_Type</tp:type> 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
@@ -315,25 +324,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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>If the connection has a 'subscribe' contact list,
+ <tp:member-ref>PresenceUpdate</tp:member-ref> 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>
+ <p>On some protocols, <tp:member-ref>RequestPresence</tp:member-ref> 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.
+ appear in the result of <tp:member-ref>GetStatuses</tp:member-ref>,
+ or in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">Statuses</tp:dbus-ref>
+ property of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ interface.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Offline" value="1">
--
1.5.6.5
More information about the Telepathy-commits
mailing list