1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
<?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: -->
|
