<?xml version="1.0" ?>
<node name="/Connection_Interface_Power_Saving"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
  >
  <tp:copyright> Copyright © 2007-2010 Collabora Limited </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
Library 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.PowerSaving">
    <tp:added version="0.21.UNRELEASED">(as stable API)</tp:added>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Some protocols support mechanisms for reducing bandwidth usage—and
        hence power usage, on mobile devices—when the user is not directly
        interacting with their IM client. For instance, Google Talk's XMPP
        server supports queueing incoming presence updates at the client's
        instruction; the client can instruct the server to deliver all
        outstanding presence updates at a later time. This interface may be
        used to instruct the connection manager to enable and disable such
        protocol-level features when a screensaver is activated, the device
        screen is locked, and so on, by calling the
        <tp:member-ref>SetPowerSaving</tp:member-ref> method.</p>

      <p>Enabling power saving SHOULD NOT change behaviour in any way
        that is noticable to a user not actively interacting with their client.
        For example, delaying presence updates somewhat is unlikely to be
        noticed by a user not staring at their device waiting for a contact to
        come online; on the other hand, requesting that the server queue
        incoming messages would be noticable by the user, so is not an
        acceptable effect of calling
        <tp:member-ref>SetPowerSaving</tp:member-ref>.</p>
    </tp:docstring>

    <method name="SetPowerSaving" tp:name-for-bindings="Set_Power_Saving">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Turn power saving mode on or off.</p>

        <tp:rationale>
          <p>Depending on the device's activity level, the
            connection can have its power saving mode turned on or off.</p>
        </tp:rationale>

        <p>Errors raised by this method indicate that power saving could not be
          enabled, which SHOULD NOT generally be treated as fatal.</p>

        <tp:rationale>
          If the CM cannot switch modes, either because of the
          protocol (<code>NotImplemented</code>), or because of the service
          (<code>NotAvailable</code>), Mission Control (or whoever manages this)
          should be made aware. The error could be ignored or, in the extreme,
          be fascist and disconnect the account.
        </tp:rationale>
      </tp:docstring>

      <arg direction="in" name="Activate" type="b">
        <tp:docstring>
          <code>True</code> if protocol-level power saving features should be
          activated; <code>False</code> if they should be de-activated.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The current connection has no power saving features.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
      </tp:possible-errors>
    </method>

    <property name="PowerSavingActive" type="b" access="read"
              tp:name-for-bindings="Power_Saving_Active">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p><code>True</code> if protocol-level power saving features are
          currently activated. This property can be changed using the
          <tp:member-ref>SetPowerSaving</tp:member-ref> method; change
          notifications is via the
          <tp:member-ref>PowerSavingChanged</tp:member-ref> signal.</p>
      </tp:docstring>
    </property>

    <signal name="PowerSavingChanged"
            tp:name-for-bindings="Power_Saving_Changed">
      <arg name="Active" type="b">
        <tp:docstring>
          The new state of the power saving feature.
        </tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        The <tp:member-ref>PowerSavingActive</tp:member-ref>
        property changed.
      </tp:docstring>
    </signal>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
