Move contents of lib/ into root directory

20070419173517-53eee-d91a15d77882d6839193c1f77be4f88803b48f58.gz

1 files changed, 313 insertions, 0 deletions

diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
new file mode 100644
index 000000000..01ae6d32c
--- /dev/null
+++ b/spec/Connection_Interface_Presence.xml
@@ -0,0 +1,313 @@
+<?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
+Library 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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
+  </tp:license>
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence">
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <method name="AddStatus">
+      <arg direction="in" name="status" type="s">
+        <tp:docstring>
+          The string identifier of the desired status
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="parms" type="a{sv}">
+        <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: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">
+      <arg direction="in" name="contacts" type="au">
+        <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: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">
+      <arg direction="out" type="a{s(ubba{ss})}">
+        <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">
+      <arg name="presence" type="a{u(ua{sa{sv}})}">
+        <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">
+      <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">
+      <arg direction="in" name="contacts" type="au">
+        <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">
+      <arg direction="in" name="time" type="u">
+        <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">
+      <arg direction="in" name="statuses" type="a{sa{sv}}">
+        <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 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 the Galago project
+    (see http://www.galago-project.org/).</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</li>
+      <li>away</li>
+      <li>brb (Be Right Back)</li>
+      <li>busy</li>
+      <li>dnd (Do Not Disturb),</li>
+      <li>xa (Extended Away)</li>
+      <li>hidden (aka Invisible)</li>
+      <li>offline</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
+        </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:enum>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->