2
<node name="/Connection_Interface_Balance"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
4
<tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright>
5
<tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
6
<tp:license xmlns="http://www.w3.org/1999/xhtml">
7
<p>This library is free software; you can redistribute it and/or
8
modify it under the terms of the GNU Lesser General Public
9
License as published by the Free Software Foundation; either
10
version 2.1 of the License, or (at your option) any later version.</p>
12
<p>This library is distributed in the hope that it will be useful,
13
but WITHOUT ANY WARRANTY; without even the implied warranty of
14
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15
Lesser General Public License for more details.</p>
17
<p>You should have received a copy of the GNU Lesser General Public
18
License along with this library; if not, write to the Free Software
19
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
22
<interface name="org.freedesktop.Telepathy.Connection.Interface.Balance">
23
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
24
<tp:added version="0.19.0">(as stable API)</tp:added>
26
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
27
<p>In many real-time communication services the user can pay for certain
28
services, typically calls to the
29
<abbr title="Public Switched Telephone Network">PSTN</abbr>,
30
in advance. In (at least) Skype, it's possible to query the current
31
balance in a machine-readable way.</p>
34
<tp:struct name="Currency_Amount">
35
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
36
<p>An amount of money in a specified currency. For example,
37
3.21 British pounds would conventionally be represented by
38
(<var>Amount</var> = <tt>321</tt>, <var>Scale</var> = <tt>2</tt>,
39
<var>Currency</var> = <tt>"GBP"</tt>), but could be represented by
40
(<var>Amount</var> = <tt>3210</tt>, <var>Scale</var> = <tt>3</tt>,
41
<var>Currency</var> = <tt>"GBP"</tt>) in a service that records
42
balance in units of 0.001 pounds.</p>
44
<p>As a special case, if <var>Amount</var> = <tt>0</tt>,
45
<var>Scale</var> = <tt>2**32 - 1</tt> (i.e. the largest possible
46
32-bit unsigned integer) and <var>Currency</var> = <tt>""</tt>, this
47
indicates an unknown amount.</p>
50
<tp:member type="i" name="Amount">
51
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
52
<p>The amount, expressed as a fixed-point number with decimal scale
53
defined by the <var>Scale</var> field; for instance, an
54
<var>Amount</var> value of <tt>1234</tt> with <var>Scale</var> of
55
<tt>2</tt> represents 12.34 in the currency unit given by the
56
<var>Currency</var> field.</p>
59
<tp:member type="u" name="Scale">
60
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
61
<p>The decimal scale for the fixed point value of the
62
<var>Amount</var> field, defining the number of rightmost decimal
63
digits from the integer value which form the fractional part of the
64
resulting currency value.</p>
66
<p>As well as defining the interpretation of <var>Amount</var>, user
67
interfaces may use this value to determine the precision with which
68
to display the amount.</p>
71
<tp:member type="s" name="Currency">
73
The currency code represented by this amount, which SHOULD be an
74
international currency code such as <tt>"EUR"</tt>, <tt>"USD"</tt>,
75
or <tt>"JPY"</tt> if possible. An empty string can be used to
76
indicate that the currency is not known.
81
<property name="AccountBalance" tp:name-for-bindings="Account_Balance"
82
access="read" type="(ius)" tp:type="Currency_Amount">
83
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
84
<p>The user's balance on the account corresponding to this <tp:dbus-ref
85
namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.
86
A negative amount may be possible on some services, and indicates
87
that the user owes money to the service provider.</p>
89
<p>On initial connection, this property may have an unknown
90
value, represented by <var>Amount</var> = <tt>0</tt>,
91
<var>Scale</var> = <tt>2**32 - 1</tt> (the largest possible 32-bit
92
unsigned integer) and <var>Currency</var> = <tt>""</tt>.</p>
96
<signal name="BalanceChanged" tp:name-for-bindings="Balance_Changed">
97
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
98
<p>Emitted when the user's balance has changed.</p>
101
<arg name="Balance" type="(ius)" tp:type="Currency_Amount">
102
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
103
<p>The new value of the <tp:member-ref>AccountBalance</tp:member-ref>
111
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
spec/Connection_Interface_Balance.xml
