Move contents of lib/ into root directory

20070419173517-53eee-d91a15d77882d6839193c1f77be4f88803b48f58.gz

1 files changed, 208 insertions, 0 deletions

diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
new file mode 100644
index 000000000..34762baf3
--- /dev/null
+++ b/spec/Connection_Interface_Avatars.xml
@@ -0,0 +1,208 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Avatars" 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.Avatars">
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <signal name="AvatarUpdated">
+      <arg name="contact" type="u">
+        <tp:docstring>
+          An integer handle for the contact whose avatar has changed
+        </tp:docstring>
+      </arg>
+      <arg name="new_avatar_token" type="s">
+        <tp:docstring>
+          Unique token for their new avatar
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Emitted when the avatar for a contact has been updated, or first
+        discovered on this connection. If the token differs from the token
+        associated with the client's cached avatar for this contact, the new
+        avatar should be requested with RequestAvatar.
+      </tp:docstring>
+    </signal>
+    <method name="GetAvatarRequirements">
+      <arg direction="out" type="as">
+        <tp:docstring>
+          An array of supported MIME types (eg image/jpeg)
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="q">
+        <tp:docstring>
+          The minimum image width in pixels
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="q">
+        <tp:docstring>
+          The minimum image height in pixels
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="q">
+        <tp:docstring>
+          The maximum image width in pixels
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="q">
+        <tp:docstring>
+          The maximum image height in pixels
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="u">
+        <tp:docstring>
+          The maximum image size in bytes
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Get the required format of avatars on this connection.
+      </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.NotAvailable"/>
+      </tp:possible-errors>
+    </method>
+    <method name="GetAvatarTokens">
+      <arg direction="in" name="contacts" type="au">
+        <tp:docstring>
+        An array of handles representing contacts
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="as">
+        <tp:docstring>
+          An array of avatar tokens or empty strings (if no avatar is set) in the
+          same order as the given array of contact handles
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Get the unique tokens for the given contacts' avatars. These tokens
+        can be persisted across connections, and should be used by the client
+        to check whether the avatars have been updated. A empty token means
+        that no avatar is set for the given contact.
+      </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.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+      </tp:possible-errors>
+    </method>
+    <method name="RequestAvatar">
+      <arg direction="in" name="contact" type="u">
+        <tp:docstring>
+          An integer handle for the contact to request the avatar for
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="ay">
+        <tp:docstring>
+          An array of bytes containing the image data
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="s">
+        <tp:docstring>
+        A string containing the image MIME type (eg image/jpeg), or empty if
+        unknown
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Request the avatar for a given contact.
+      </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:possible-errors>
+    </method>
+    <method name="SetAvatar">
+      <arg direction="in" name="avatar" type="ay">
+        <tp:docstring>
+          An array of bytes representing the avatar image data
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="mime_type" type="s">
+        <tp:docstring>
+          A string representing the image MIME type
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="s">
+        <tp:docstring>
+          The string token of the new avatar
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Set a new avatar image for this connection. The avatar image must
+        respect the requirements obtained by GetAvatarRequirements.
+      </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.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+      </tp:possible-errors>
+    </method>
+    <method name="ClearAvatar">
+      <tp:added version="0.15.0" />
+      <tp:docstring>
+        Remove the avatar image for this connection.
+      </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>
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface for requesting avatars for contacts on a given connection,
+    receiving notification when avatars are changed, and publishing your own
+    avatar.</p>
+
+    <p>Avatars are identified by a unique (per contact) token which represents a
+    hash or timestamp (depending on the protocol) of the contacts' avatar data.
+    An empty token means that an avatar has not been set for this contact, and
+    a changed token implies the contact's avatar has changed, but the strings
+    should otherwise be considered opaque by clients.</p>
+
+    <p>A client should use GetAvatarTokens to request the tokens for the avatars
+    of all the contacts it is interested in when it connects. The avatars can
+    then be retreived using RequestAvatar for the corresponding contact.
+    Clients should bind to the AvatarChanged signal and request a new copy of
+    the avatar when a contacts' avatar token changes. Clients should cache the
+    token and data of each contact's avatar between connections, to avoid
+    repeatedly retrieving the same avatar.</p>
+
+    <p>To publish an avatar, a client should use SetAvatar to provide an image
+    which meets the requirements returned by the GetAvatarRequirements
+    function. On some protocols the avatar is stored on the server, so setting
+    the avatar is persistent, but on others it is transferred via a peer to
+    peer mechanism, so needs to be set every connection. Hence, on every
+    connection, clients should inspect the avatar token of the connection's
+    self handle, and set the avatar if it is an empty string (and may
+    optionally replace it if the token corresponds to a different avatar).</p>
+
+    <p>To remove the published avatar on protocols which have persistent avatars,
+    a client should use the ClearAvatar method. This method can safely be used
+    even if there is no avatar for this connection.</p>
+    </tp:docstring>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->