Move contents of lib/ into root directory

20070419173517-53eee-d91a15d77882d6839193c1f77be4f88803b48f58.gz

1 files changed, 458 insertions, 0 deletions

diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
new file mode 100644
index 000000000..922d8e568
--- /dev/null
+++ b/spec/Channel_Interface_Group.xml
@@ -0,0 +1,458 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Group" 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.Channel.Interface.Group">
+    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+    <method name="AddMembers">
+      <arg direction="in" name="contacts" type="au">
+        <tp:docstring>
+          An array of contact handles to invite to the channel
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="message" type="s">
+        <tp:docstring>
+          A string message, which can be blank if desired
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Invite all the given contacts into the channel, or accept requests for
+          channel membership for contacts on the pending local list.</p>
+        
+        <p>A message may be provided along with the request, which will be sent
+        to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and
+        CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT flags to see in which cases this
+        message should be provided.</p>
+      </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.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
+      </tp:possible-errors>
+    </method>
+    <method name="GetAllMembers">
+      <arg direction="out" type="au">
+        <tp:docstring>
+          array of handles of current members
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="au">
+        <tp:docstring>
+          array of handles of local pending members
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="au">
+        <tp:docstring>
+          array of handles of remote pending members
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Returns arrays of all current, local and remote pending channel
+        members.
+      </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:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u">
+      <tp:flag suffix="Can_Add" value="1">
+        <tp:docstring>
+            The AddMembers method can be used to add or invite members who are
+            not already in the local pending list (which is always valid).
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Can_Remove" value="2">
+        <tp:docstring>
+            The RemoveMembers method can be used to remove channel members
+            (removing those on the pending local list is always valid).
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Can_Rescind" value="4">
+        <tp:docstring>
+            The RemoveMembers method can be used on people on the remote
+            pending list.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Message_Add" value="8">
+        <tp:docstring>
+            A message may be sent to the server when calling AddMembers on
+            contacts who are not currently pending members.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Message_Remove" value="16">
+        <tp:docstring>
+            A message may be sent to the server when calling RemoveMembers on
+            contacts who are currently channel members.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Message_Accept" value="32">
+        <tp:docstring>
+            A message may be sent to the server when calling AddMembers on
+            contacts who are locally pending.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Message_Reject" value="64">
+        <tp:docstring>
+            A message may be sent to the server when calling RemoveMembers on
+            contacts who are locally pending.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Message_Rescind" value="128">
+        <tp:docstring>
+            A message may be sent to the server when calling RemoveMembers on
+            contacts who are remote pending.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Channel_Specific_Handles" value="256">
+        <tp:docstring>
+            The members of this group have handles which are specific to
+            this channel, and are not valid as general-purpose handles on
+            the connection. Depending on the channel, it may be possible to
+            call GetHandleOwners to find the owners of these handles, which
+            should be done if you wish to eg subscribe to the contact's
+            presence.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Only_One_Group" value="512">
+        <tp:docstring>
+            Placing a contact in multiple groups of this type is not allowed
+            and will raise NotAvailable (on services where contacts may only
+            be in one user-defined group, user-defined groups will have
+            this flag).
+        </tp:docstring>
+      </tp:flag>
+    </tp:flags>
+    <method name="GetGroupFlags">
+      <arg direction="out" type="u">
+        <tp:docstring>
+          The bitwise OR of zero or more values from ChannelGroupFlags
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Returns an integer representing the bitwise-OR of flags on this
+        channel. The user interface can use this to present information about
+        which operations are currently valid.
+      </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>
+    <method name="GetHandleOwners">
+      <arg direction="in" name="handles" type="au">
+        <tp:docstring>
+          A list of integer handles representing members of the channel
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="au">
+        <tp:docstring>
+          An array of integer handles representing the owner handles of
+          the given room members, in the same order, or 0 if the
+          owner is not available
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on
+        the channel, then the handles of the group members are specific
+        to this channel, and are not meaningful in a connection-wide
+        context such as contact lists. This method allows you to find
+        the owner of the handle if it can be discovered in this channel,
+        or 0 if the owner is not available.
+      </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.NotAvailable">
+          <tp:docstring>
+            This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag,
+            so handles in this channel are globally meaningful and calling
+            this method is not necessary
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            One of the given handles is not a member
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+    <method name="GetLocalPendingMembers">
+      <arg direction="out" type="au"/>
+      <tp:docstring>
+        Returns an array of handles representing contacts requesting
+        channel membership and awaiting local approval with AddMembers.
+      </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>
+    <method name="GetLocalPendingMembersWithInfo">
+      <tp:added version="0.15.0" />
+      <tp:docstring>
+        Returns an array of structs containing handles representing contacts
+        requesting channel membership and awaiting local approval with
+        AddMembers.  
+      </tp:docstring>
+      <arg direction="out" type="a(uuus)">
+        <tp:docstring>
+          An array of structs containing:
+          <ul>
+            <li>
+              A handle representing the contact requesting channel membership
+            </li>
+            <li>
+              A handle representing the contact making the request, or 0 if
+              unknown
+            </li>
+            <li>
+              The reason for the request: one of the values of
+              ChannelGroupChangeReason
+            </li>
+            <li> 
+              A string message containing the reason for the request if any (or
+              blank if none)
+            </li>
+          </ul>
+        </tp:docstring>
+      </arg>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+      </tp:possible-errors>
+    </method>
+    <method name="GetMembers">
+      <arg direction="out" type="au"/>
+      <tp:docstring>
+        Returns an array of handles for the members of this channel.
+      </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>
+    <method name="GetRemotePendingMembers">
+      <arg direction="out" type="au"/>
+      <tp:docstring>
+        Returns an array of handles representing contacts who have been
+        invited to the channel and are awaiting remote approval.
+      </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>
+    <method name="GetSelfHandle">
+      <arg direction="out" type="u"/>
+      <tp:docstring>
+        Returns the handle for the user on this channel (which can also be a
+        local or remote pending member) or 0 if the user not a member at all
+        (which is likely to be the case, for instance, on Type.ContactList
+        channels). Note that this is different from the connection
+        GetSelfHandle on some protocols, so the value of this handle should
+        always be used with the methods of this interface.
+      </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="GroupFlagsChanged">
+      <arg name="added" type="u">
+        <tp:docstring>
+          A bitwise OR of the flags which have been set
+        </tp:docstring>
+      </arg>
+      <arg name="removed" type="u">
+        <tp:docstring>
+          A bitwise OR of the flags which have been cleared
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Emitted when the flags as returned by GetGroupFlags are changed.
+        The user interface should be updated as appropriate.
+      </tp:docstring>
+    </signal>
+    <tp:enum name="Channel_Group_Change_Reason" type="u">
+      <tp:enumvalue suffix="None" value="0">
+        <tp:docstring>
+            No reason was provided for this change.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Offline" value="1">
+        <tp:docstring>
+            The change is due to a user going offline.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Kicked" value="2">
+        <tp:docstring>
+            The change is due to a kick operation.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Busy" value="3">
+        <tp:docstring>
+            The change is due to a busy indication.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Invited" value="4">
+        <tp:docstring>
+            The change is due to an invitation.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Banned" value="5">
+        <tp:docstring>
+            The change is due to a kick+ban operation.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Error" value="6">
+        <tp:docstring>
+            The change is due to an error occurring.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Invalid_Contact" value="7">
+        <tp:docstring>
+            The change is because the requested contact does not exist.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="No_Answer" value="8">
+        <tp:docstring>
+            The change is because the requested contact did not respond.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+    <signal name="MembersChanged">
+      <arg name="message" type="s">
+        <tp:docstring>
+          A string message from the server, or blank if not
+        </tp:docstring>
+      </arg>
+      <arg name="added" type="au">
+        <tp:docstring>
+          A list of members added to the channel
+        </tp:docstring>
+      </arg>
+      <arg name="removed" type="au">
+        <tp:docstring>
+          A list of members removed from the channel
+        </tp:docstring>
+      </arg>
+      <arg name="local_pending" type="au">
+        <tp:docstring>
+          A list of members who are pending local approval
+        </tp:docstring>
+      </arg>
+      <arg name="remote_pending" type="au">
+        <tp:docstring>
+          A list of members who are pending remote approval
+        </tp:docstring>
+      </arg>
+      <arg name="actor" type="u">
+        <tp:docstring>
+          The contact handle of the person who made the change, or 0
+          if not known
+        </tp:docstring>
+      </arg>
+      <arg name="reason" type="u">
+        <tp:docstring>
+          A reason for the change: one of the values of
+          ChannelGroupChangeReason
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Emitted when contacts join any of the three lists (members, local
+        pending or remote pending).  Contacts are listed in the removed
+        list when they leave any of the three lists. There may also be
+        a message from the server regarding this change, which may be
+        displayed to the user if desired.
+      </tp:docstring>
+    </signal>
+    <method name="RemoveMembers">
+      <arg direction="in" name="contacts" type="au">
+        <tp:docstring>
+          An array of contact handles to remove from the channel
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="message" type="s">
+        <tp:docstring>
+          A string message, which can be blank if desired
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Requests the removal of contacts from a channel, reject their request
+        for channel membership on the pending local list, or rescind their
+        invitation on the pending remote list. A message may be provided along
+        with the request, which will be sent to the server if supported. See
+        the CHANNEL_GROUP_FLAG_MESSAGE_REMOVE,
+        CHANNEL_GROUP_FLAG_MESSAGE_REJECT and
+        CHANNEL_GROUP_FLAG_MESSAGE_RESCIND flags to see in which cases this
+        message should be provided.
+      </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.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+      </tp:possible-errors>
+    </method>
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>Interface for channels which have multiple members, and where the members
+    of the channel can change during its lifetime. Your presence in the channel
+    cannot be presumed by the channel's existence (for example, a channel you
+    may request membership of but your request may not be granted).</p>
+
+  <p>This interface implements three lists: a list of current members, and two
+    lists of local pending and remote pending members. Contacts on the remote
+    pending list have been invited to the channel, but the remote user has not
+    accepted the invitation. Contacts on the local pending list have requested
+    membership of the channel, but the local user of the framework must accept
+    their request before they may join. A single contact should never appear on
+    more than one of the three lists. The lists are empty when the channel is
+    created, and the MembersChanged signal should be emitted when information
+    is retrieved from the server, or changes occur.</p>
+
+  <p>Addition of members to the channel may be requested by using AddMembers. If
+    remote acknowledgement is required, use of the AddMembers method will cause
+    users to appear on the remote pending list. If no acknowledgement is
+    required, AddMembers will add contacts to the member list directly.  If a
+    contact is awaiting authorisation on the local pending list, AddMembers
+    will grant their membership request.</p>
+
+  <p>Removal of contacts from the channel may be requested by using
+    RemoveMembers.  If a contact is awaiting authorisation on the local pending
+    list, RemoveMembers will refuse their membership request. If a contact is
+    on the remote pending list but has not yet accepted the invitation,
+    RemoveMembers will rescind the request if possible.</p>
+
+  <p>It should not be presumed that the requester of a channel implementing this
+    interface is immediately granted membership, or indeed that they are a
+    member at all, unless they appear in the list. They may, for instance,
+    be placed into the remote pending list until a connection has been
+    established or the request acknowledged remotely.</p>
+    </tp:docstring>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->