~ubuntu-branches/ubuntu/feisty/libtelepathy/feisty

<?xml version="1.0" ?>

<node name="/Channel_Type_Room_List" 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.Type.RoomList">

    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>

    <method name="GetListingRooms">

      <arg direction="out" type="b">

        <tp:docstring>

          A boolean indicating if room listing is in progress

        </tp:docstring>

      </arg>

      <tp:docstring>

        Check to see if there is already a room list request in progress

        on this channel.

      </tp:docstring>

    </method>

    <signal name="GotRooms">

      <arg name="rooms" type="a(usa{sv})">

        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">

          An array of structs containing:

          <ul>

            <li>an integer room handle</li>

            <li>a string representing the D-Bus interface name of the channel type</li>

            <li>a dictionary mapping string keys to variant boxed information</li>

          </ul>

        </tp:docstring>

      </arg>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">

        <p>Emitted when information about rooms on the server becomes available.

        The array contains the room handle (as can be passed to the

        RequestChannel method with HANDLE_TYPE_ROOM), the channel

        type, and a dictionary containing further information about the

        room as available. The following well-known keys and types are

        recommended for use where appropriate:</p>

 

        <dl>

          <dt>s:name</dt><dd>The name of the room if different from the handle</dd>

          <dt>s:subject</dt><dd>The subject of the room</dd>

          <dt>u:members</dt><dd>The number of members of the room</dd>

          <dt>b:password</dt><dd>True if the room requires a password to enter</dd>

          <dt>b:invite-only</dt><dd>True if you cannot join the room, but must be invited</dd>

        </dl>

      </tp:docstring>

    </signal>

    <method name="ListRooms">

      <tp:docstring>

        Request the list of rooms from the server. The ListingRooms signal

        should be emitted when this request is being processed, GotRooms when

        any room information is received, and ListingRooms when the request

        is complete.

      </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:possible-errors>

    </method>

    <method name="StopListing">

      <tp:docstring>

        Stop the room listing if it's in progress, but don't close the channel.

        The ListingRooms signal should be emitted when the listing stops.

      </tp:docstring>

    </method>

    <signal name="ListingRooms">

      <arg name="listing" type="b">

        <tp:docstring>A boolean indicating if room listing is in progress</tp:docstring>

      </arg>

      <tp:docstring>

        Emitted to indicate whether or not room listing request is currently

        in progress.

      </tp:docstring>

    </signal>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">

      <p>A channel type for listing named channels available on the server. Once the

    ListRooms method is called, it emits signals for rooms present on the

    server, until you Close this channel. In some cases, it may not be possible

    to stop the deluge of information from the server. This channel should be

    closed when the room information is no longer being displayed, so that the

    room handles can be freed.</p>

 

    <p>This channel type may be implemented as a singleton on some protocols, so

    clients should be prepared for the eventuality that they are given a

    channel that is already in the middle of listing channels. The ListingRooms

    signal, or GetListingRooms method, can be used to check this.</p>

    </tp:docstring>

  </interface>

</node>

<!-- vim:set sw=2 sts=2 et ft=xml: -->