diff options
Diffstat (limited to 'spec/Connection_Interface_Communication_Policy.xml')
| -rw-r--r-- | spec/Connection_Interface_Communication_Policy.xml | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/spec/Connection_Interface_Communication_Policy.xml b/spec/Connection_Interface_Communication_Policy.xml new file mode 100644 index 0000000..9a92fa0 --- /dev/null +++ b/spec/Connection_Interface_Communication_Policy.xml @@ -0,0 +1,163 @@ +<?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="Chanel_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> |