<?xml version="1.0" ?>
<node name="/Connection_Interface_Balance"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2009 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.Balance">
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
    <tp:added version="0.19.0">(as stable API)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>In many real-time communication services the user can pay for certain
        services, typically calls to the
        <abbr title="Public Switched Telephone Network">PSTN</abbr>,
        in advance. In (at least) Skype, it's possible to query the current
        balance in a machine-readable way.</p>
    </tp:docstring>

    <tp:struct name="Currency_Amount">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>An amount of money in a specified currency. For example,
          3.21 British pounds would conventionally be represented by
          (<var>Amount</var> = <tt>321</tt>, <var>Scale</var> = <tt>2</tt>,
          <var>Currency</var> = <tt>"GBP"</tt>), but could be represented by
          (<var>Amount</var> = <tt>3210</tt>, <var>Scale</var> = <tt>3</tt>,
          <var>Currency</var> = <tt>"GBP"</tt>) in a service that records
          balance in units of 0.001 pounds.</p>

        <p>As a special case, if <var>Amount</var> = <tt>0</tt>,
          <var>Scale</var> = <tt>2**32 - 1</tt> (i.e.  the largest possible
          32-bit unsigned integer) and <var>Currency</var> = <tt>""</tt>, this
          indicates an unknown amount.</p>
      </tp:docstring>

      <tp:member type="i" name="Amount">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The amount, expressed as a fixed-point number with decimal scale
            defined by the <var>Scale</var> field; for instance, an
            <var>Amount</var> value of <tt>1234</tt> with <var>Scale</var> of
            <tt>2</tt> represents 12.34 in the currency unit given by the
            <var>Currency</var> field.</p>
        </tp:docstring>
      </tp:member>
      <tp:member type="u" name="Scale">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The decimal scale for the fixed point value of the
            <var>Amount</var> field, defining the number of rightmost decimal
            digits from the integer value which form the fractional part of the
            resulting currency value.</p>

          <p>As well as defining the interpretation of <var>Amount</var>, user
            interfaces may use this value to determine the precision with which
            to display the amount.</p>
        </tp:docstring>
      </tp:member>
      <tp:member type="s" name="Currency">
        <tp:docstring>
          The currency code represented by this amount, which SHOULD be an
          international currency code such as <tt>"EUR"</tt>, <tt>"USD"</tt>,
          or <tt>"JPY"</tt> if possible. An empty string can be used to
          indicate that the currency is not known.
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <property name="AccountBalance" tp:name-for-bindings="Account_Balance"
      access="read" type="(ius)" tp:type="Currency_Amount">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The user's balance on the account corresponding to this <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.
          A negative amount may be possible on some services, and indicates
          that the user owes money to the service provider.</p>

        <p>On initial connection, this property may have an unknown
          value, represented by <var>Amount</var> = <tt>0</tt>,
          <var>Scale</var> = <tt>2**32 - 1</tt> (the largest possible 32-bit
          unsigned integer) and <var>Currency</var> = <tt>""</tt>.</p>
      </tp:docstring>
    </property>

    <property name="ManageCreditURI"
              tp:name-for-bindings="Manage_Credit_URI"
              access="read" type="s">
      <tp:added version="0.22.2"/>
      <tp:docstring>
        A URI the user may visit via the web browser to manage and top-up their
        account balance. This property is not guaranteed to be well-defined
        until the connection becomes Connected; there is no change
        notification.

        <tp:rationale>
          Different protocols and even servers or gateways (e.g. SIP and XMPP
          PSTN gateways) will have a different website used to manage a user's
          account balance. This property enables the client to provide that
          to the user. A Connection Manager MAY set this itself (because it is
          static or discoverable), or expose it as a connection parameter.
        </tp:rationale>
      </tp:docstring>
    </property>

    <signal name="BalanceChanged" tp:name-for-bindings="Balance_Changed">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when the user's balance has changed.</p>
      </tp:docstring>

      <arg name="Balance" type="(ius)" tp:type="Currency_Amount">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The new value of the <tp:member-ref>AccountBalance</tp:member-ref>
            property.</p>
        </tp:docstring>
      </arg>
    </signal>

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