1 files changed, 195 insertions, 0 deletions
diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml
new file mode 100644
index 0000000..31f1554
--- /dev/null
+++ b/spec/Connection_Interface_Anonymity.xml
@@ -0,0 +1,195 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Anonymity"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2010 Collabora Ltd.</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
+      Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA
+      02110-1301, USA.</p>
+  </tp:license>
+
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.Anonymity">
+    <tp:added version="0.19.7">(as stable API)</tp:added>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface to support anonymity settings on a per-connection basis.
+        This defines what personal identifying information a remote contact
+        may or may not see.  For example, GSM might use this for CLIR, while
+        SIP might use this for privacy service requests.</p>
+    </tp:docstring>
+
+    <tp:flags name="Anonymity_Mode_Flags" value-prefix="Anonymity_Mode" type="u">
+      <tp:docstring>
+        <p>Flags for the various types of anonymity modes.  These modes are solely to
+        inform the CM of the desired anonymous settings.  It is up to the
+        CM to determine whether the anonymity modes should be handled within
+        the CM itself, or whether the network that a CM might be talking to
+        should be enforcing anonymity.</p>
+
+        <p>CMs MAY support only a subset of these modes, and specific
+        connections MAY support none at all.</p>
+      </tp:docstring>
+
+      <tp:flag value="1" suffix="Client_Info">
+        <tp:docstring>
+          <p>Obscure any information that provides user identification,
+          user-agent identification or personal details. Examples of this
+          information might be GSM CallerID, SIP from address, various
+          informational email headers, etc.</p>
+
+          <p>The CM should scrub/replace any of this information before
+          passing messages or data onto the network. Note that a CM which
+          has the option of obscuring the information at the CM or privacy
+          service level would choose both (anonymity services are opaque
+          to clients of this interface).</p>
+
+          <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes.
+          If they are set, the CM MUST respect Client_Info and ignore
+          Show_Client_Info.</p>
+        </tp:docstring>
+      </tp:flag>
+
+      <tp:flag value="2" suffix="Show_Client_Info">
+        <tp:docstring>
+          <p>Explicitly request showing of client information. In connection
+          context, this can be used to override service default. In channel
+          context, this overrides connection anonymity modes.</p>
+
+          <tp:rationale>
+            <p>In GSM, it's possible to have CLIR enabled by default, and
+              explicitly suppress CLIR for a single phone call.</p>
+          </tp:rationale>
+
+          <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes.
+          If they are set, the CM MUST respect Client_Info and ignore
+          Show_Client_Info. The CM MAY set both Client_Info and Show_Client_Info
+          in <tp:member-ref>SupportedAnonymityModes</tp:member-ref> to indicate
+          its support for explicitly hiding and publicising client information.
+          </p>
+        </tp:docstring>
+      </tp:flag>
+
+      <tp:flag value="4" suffix="Network_Info">
+        <tp:docstring>
+          <p>Obscure any originating IP address information, contact URIs,
+          and anonymize all traffic involved with sending/receiving any
+          media streams or call content.
+          Examples of this include the "headers" portions of
+          <a href="http://www.rfc-editor.org/rfc/rfc3323.txt">RFC 3323</a> as
+          well as the History-Info (described in
+          <a href="http://www.rfc-editor.org/rfc/rfc4244.txt">RFC 4244</a>)
+          for a SIP CM.</p>
+
+          <p>This SHOULD have the effect of hiding address information from
+          the remote contact (ie, the contact cannot know what IP address
+          the session is originated from). Obviously the network still needs
+          to be able to route information between contacts, so this provides
+          no guarantees of what can be seen by intermediaries.</p>
+        </tp:docstring>
+      </tp:flag>
+    </tp:flags>
+
+    <property name="SupportedAnonymityModes" type="u" access="read"
+      tp:type="Anonymity_Mode_Flags" tp:name-for-bindings="Supported_Anonymity_Modes">
+      <tp:docstring>
+        The anonymity modes supported by the CM for this connection.  Once
+        Connection.Status has moved to Connected, this property MUST NOT change.
+      </tp:docstring>
+    </property>
+
+    <property name="AnonymityMandatory" type="b" access="readwrite"
+      tp:name-for-bindings="Anonymity_Mandatory">
+      <tp:docstring>
+        <p>This specifies whether or not the anonymity settings MUST be respected
+          by the CM and any intermediaries between the local and remote contacts.
+          If this is set to true but anonymity settings cannot be followed, then
+          the session MUST be denied with a
+          <code>org.freedesktop.Telepathy.Errors.WouldBreakAnonymity</code>
+          error.
+          Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref>
+          SHOULD also set this property first (rather than accepting the CM's
+          default value).</p>
+
+        <p>This property SHOULD also be made available as a parameter of the
+          same (fully-qualified) name to <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>,
+          with the DBus_Property flag in its
+          <tp:type>Conn_Mgr_Param_Flags</tp:type>. For connections managed
+          by the <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>,
+          this property SHOULD be set via the Account Manager as follows:</p>
+
+        <blockquote>
+          <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account"
+            >UpdateParameters</tp:dbus-ref>({
+              "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityMandatory": <var>new_value</var>
+              }, [])</code>
+        </blockquote>
+      </tp:docstring>
+    </property>
+
+    <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
+      access="readwrite" tp:name-for-bindings="Anonymity_Modes">
+      <tp:docstring>
+        <p>The currently enabled anonymity modes for the connection. Setting
+          has the effect of requesting new modes for the connection, and may
+          raise an error if the unsupported modes are set. Successfully changing
+          the modes will result in emission of
+          <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p>
+
+        <p>This property SHOULD also be made available as a parameter of the
+          same (fully-qualified) name to <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>,
+          with the DBus_Property flag in its
+          <tp:type>Conn_Mgr_Param_Flags</tp:type>. For connections managed
+          by the <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>,
+          this property SHOULD be set via the Account Manager as follows:</p>
+
+        <blockquote>
+          <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account"
+            >UpdateParameters</tp:dbus-ref>({
+              "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityModes": <var>new_value</var>
+              }, [])</code>
+        </blockquote>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            An unsupported mode was supplied. Supported modes are specified
+            in the SupportedAnonymityModes property, and this should be
+            checked prior to setting AnonymityModes.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </property>
+
+    <signal name="AnonymityModesChanged"
+      tp:name-for-bindings="Anonymity_Modes_Changed">
+      <tp:docstring>
+        Emitted when the anonymity mode has changed.
+      </tp:docstring>
+
+      <arg name="Modes" type="u" tp:type="Anonymity_Mode_Flags">
+        <tp:docstring>
+          The new anonymity modes for this connection.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->