<?xml version="1.0" ?>
<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>
Copyright © 2005-2011 Collabora Limited
Copyright © 2005-2009 Nokia Corporation
Copyright © 2006 INdT
  </tp:copyright>
  <tp:license>
    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.

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
Lesser General Public License for more details.

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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  </tp:license>
  <interface name="org.freedesktop.Telepathy.Channel.Interface.Password">
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:flags name="Channel_Password_Flags" value-prefix="Channel_Password_Flag" type="u">
      <tp:flag suffix="Provide" value="8">
        <tp:docstring>
          The <tp:member-ref>ProvidePassword</tp:member-ref> method must be
          called now for the user to join the channel
        </tp:docstring>
      </tp:flag>
      <tp:flag suffix="Hint" value="4">
        <tp:added version="0.25.0"/>
        <tp:docstring>
          The <tp:dbus-ref namespace="ofdT.Channel.Interface">RoomConfig1.PasswordHint</tp:dbus-ref>
          contains a hint for the password.
        </tp:docstring>
      </tp:flag>
    </tp:flags>
    <method name="GetPasswordFlags" tp:name-for-bindings="Get_Password_Flags">
      <arg direction="out" type="u" tp:type="Channel_Password_Flags"
        name="Password_Flags">
        <tp:docstring>
          An integer with the logical OR of all the flags set
          (values of ChannelPasswordFlags)
        </tp:docstring>
      </arg>
      <tp:docstring>
        Returns the bitwise-OR of the flags relevant to the password 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>
    <signal name="PasswordFlagsChanged"
      tp:name-for-bindings="Password_Flags_Changed">
      <arg name="Added" type="u" tp:type="Channel_Password_Flags">
        <tp:docstring>
          A bitwise OR of the flags which have been set
        </tp:docstring>
      </arg>
      <arg name="Removed" type="u" tp:type="Channel_Password_Flags">
        <tp:docstring>
          A bitwise OR of the flags which have been cleared
        </tp:docstring>
      </arg>
      <tp:docstring>
        Emitted when the flags as returned by
        <tp:member-ref>GetPasswordFlags</tp:member-ref> are changed.
        The user interface should be updated as appropriate.
      </tp:docstring>
    </signal>
    <method name="ProvidePassword" tp:name-for-bindings="Provide_Password">
      <arg direction="in" name="Password" type="s">
        <tp:docstring>
          The password
        </tp:docstring>
      </arg>
      <arg direction="out" type="b" name="Correct">
        <tp:docstring>
          A boolean indicating whether or not the password was correct
        </tp:docstring>
      </arg>
      <tp:docstring>
        Provide the password so that the channel can be joined. Must be
        called with the correct password in order for channel joining to
        proceed if the 'provide' password flag is set.
      </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:possible-errors>
    </method>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Interface for channels that may have a password set that users need
        to provide before being able to join. The
        <tp:member-ref>GetPasswordFlags</tp:member-ref> method and the
        associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref>
        signal indicate whether the user must now provide a password to join
        the channel.</p>

      <p>Once the user has joined the channel, the current
        password-protectedness of the room can be checked (and possibly
        modified) using the <tp:dbus-ref
        namespace='ofdT.Channel.Interface'>RoomConfig1</tp:dbus-ref>
        interface, if implemented.</p>
    </tp:docstring>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
