<?xml version="1.0" ?>
<node name="/Connection_Interface_Communication_Policy"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
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
Library 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.Connection.Interface.CommunicationPolicy.DRAFT"
     tp:causes-havoc="experimental">
    <tp:added version="0.21.1">(draft 1)</tp:added>
    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>
        This interface supports controlling which contacts are allowed
        to initiate text chats, incoming calls, and other forms of
        communication as supported by the underlying protocol. The
        policies supported for different communication methods on this
        connection are listed in the
        <tp:member-ref>SupportedPolicies</tp:member-ref> property. The
        current configuration is held in
        <tp:member-ref>ActivePolicies</tp:member-ref>; it can be modified
        using <tp:member-ref>SetPolicy</tp:member-ref>, and changes
        are signalled by <tp:member-ref>PolicyChanged</tp:member-ref>.
      </p>
    </tp:docstring>

    <tp:mapping name="Active_Policies_Map">
      <tp:docstring>
        A mapping of communication methods (channel types), and their
        associated policy.
      </tp:docstring>

      <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type">
        <tp:docstring>
          The channel interface with the policy.
        </tp:docstring>
      </tp:member>

      <tp:member type="(uv)" tp:type="Access_Control" name="Active_Policy">
        <tp:docstring>
          The active policy for this channel type.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <property name="SupportedPolicies"
              tp:name-for-bindings="Supported_Policies" access="read"
              type="a(asau)" tp:type="Supported_Policy[]">
      <tp:docstring>
        The communication policies supported by this connection.
      </tp:docstring>
    </property>

    <property name="ActivePolicies" tp:name-for-bindings="Active_Policies"
              access="read" type="a{s(uv)}" tp:type="Active_Policies_Map">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The active communication policies on this
        connection. Communication methods that are not in this
        mapping are considered open.</p>

        <p>For example, to allow incoming calls only from contacts
          buddy list, and to allow text messages from anyone,
          the policy would look like this:</p>

        <pre>
{
    'org.freedesktop.Telepathy.Channel.Type.Text' : Access_Control_Type_Open,
    'org.freedesktop.Telepathy.Channel.Type.Call' : Access_Control_Type_Publish_List
}
        </pre>

        <p>Changes to this property are signalled by
          <tp:member-ref>PolicyChanged</tp:member-ref>.</p>
      </tp:docstring>
    </property>

    <method name="SetPolicy" tp:name-for-bindings="Set_Policy">
      <tp:docstring>
        Set a policy for a communication method (channel
        type). Depending on the server or protocol, more than one
        communication method could be bound to the same policy, if
        calling this method on one channel type changes the policy on
        another channel type, the <tp:member-ref>PolicyChanged</tp:member-ref>
        signal that would follow would include all the channel types
        that have an altered policy.
      </tp:docstring>
      <arg name="Channel_Type" direction="in" type="s"
           tp:type="DBus_Interface">
        <tp:docstring>
          The channel type to set the policy for.
        </tp:docstring>
      </arg>
      <arg name="Policy" direction="in" type="(uv)"
           tp:type="Access_Control">
        <tp:docstring>
          The policy to set for this channel.
        </tp:docstring>
      </arg>
    </method>

    <signal name="PolicyChanged" tp:name-for-bindings="Policy_Changed">
      <tp:docstring>
        <tp:member-ref>ActivePolicies</tp:member-ref> has
        changed. This occurs when the server unilaterally changed the
        policy or <tp:member-ref>SetPolicy</tp:member-ref> has been
        called.
      </tp:docstring>
      <arg name="Changed_Policies" type="a{s(uv)}"
           tp:type="Active_Policies_Map">
        <tp:docstring>
          A subset of the active policies that have changed.
        </tp:docstring>
      </arg>
    </signal>

    <tp:struct name="Supported_Policy" array-name="Supported_Policy_List">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The communication methods (channel types), and the policies
        that can be applied to them. This is server and protocol
        dependant.</p>

        <p>Grouped channel types will always have the same policy applied
        to them.</p>

        <tp:rationale>
          Different protocols have different limitations to the
          granularity of communication policies. One protocol might be
          able to set a different policy for VoIP calls and text chat,
          while another protocol might only be able to set one policy
          to both VoIP and text chat.
        </tp:rationale>
      </tp:docstring>
      <tp:member type="as" tp:type="DBus_Interface[]"
        name="Channel_Types">
        <tp:docstring>
          A list of channel interfaces that support these policies.
        </tp:docstring>
      </tp:member>
      <tp:member type="au" tp:type="Access_Control_Type[]"
        name="Supported_Policies">
        <tp:docstring>
          A list of supported policies.
        </tp:docstring>
      </tp:member>
    </tp:struct>

  </interface>
</node>
