<?xml version="1.0" ?>
<node name="/Connection_Interface_Keepalive"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">

  <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2010 Nokia Corporation</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.Keepalive.DRAFT"
    tp:causes-havoc="experimental">
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
    <tp:added version="0.21.2">(draft 1)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Most messaging protocols allow the client to send periodic
        content-less pings to the server when the connection is otherwise idle,
        to reassure both itself and the server that its connection is still
        alive. Depending on the nature of the network connection, and the
        device running the client, the desired interval between such pings may
        vary.</p>

      <tp:rationale>
        <p>For instance, on a mobile handset connected via 3G,
          overly-frequent keepalives can drain the battery through needlessly
          waking up the radio, and a relatively high interval is appropiate. By
          contrast, a desktop computer is less likely to be asleep in the first
          place, and users expect dropped connections to be noticed as soon as
          possible.</p>
      </tp:rationale>

      <p>This interface provides a
        <tp:member-ref>KeepaliveInterval</tp:member-ref> property which
        controls the frequency of keepalive pings, if any. Connection managers
        implementing this property should also include it in <tp:dbus-ref
        namespace='org.freedesktop.Telepathy'>Protocol.Parameters</tp:dbus-ref>
        with the <code>DBus_Property</code> flag, allowing the desired value to
        be stored in <tp:dbus-ref
          namespace='org.freedesktop.Telepathy'>Account.Parameters</tp:dbus-ref>
        and passed onto the connection by the account manager.</p>
    </tp:docstring>

    <property name="KeepaliveInterval" type="u" access="readwrite"
              tp:name-for-bindings="Keepalive_Interval"
              tp:is-connection-parameter='och aye'>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The time in seconds between pings sent to the server to ensure that
          the connection is still alive, or <tt>0</tt> to disable such
          pings.</p>

        <p>This property (and parameter) supersedes the older
          <tt>keepalive-interval</tt>
          <tp:type>Connection_Parameter_Name</tp:type>.</p>
      </tp:docstring>
    </property>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
