<?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 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>,
          clients (other than the account manager itself) SHOULD set this
          property via the Account's <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Account">UpdateParameters</tp:dbus-ref>
          method.</p>
      </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 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>,
          clients (other than the account manager itself) SHOULD set this
          property via the Account's <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Account">UpdateParameters</tp:dbus-ref>
          method.</p>
      </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: -->
