[telepathy-spec/master] fd.o #24903: add Balance interface
Simon McVittie
simon.mcvittie at collabora.co.uk
Mon Nov 30 09:08:01 PST 2009
Based on a proposal from Mikhail Zabaluev and Naveen Verma.
Changes from their proposal:
* reserve (0, 2**32, "") to represent an unknown balance
* allow currency to be "" if we weren't told (the user can hopefully guess
from context...)
* add ChangeNotification property and RequestBalance method to cope with
services where this information is poll-only (I don't know of any, but
I'm sure they exist!)
---
spec/Connection_Interface_Balance.xml | 143 +++++++++++++++++++++++++++++++++
spec/all.xml | 1 +
2 files changed, 144 insertions(+), 0 deletions(-)
create mode 100644 spec/Connection_Interface_Balance.xml
diff --git a/spec/Connection_Interface_Balance.xml b/spec/Connection_Interface_Balance.xml
new file mode 100644
index 0000000..fae5709
--- /dev/null
+++ b/spec/Connection_Interface_Balance.xml
@@ -0,0 +1,143 @@
+<?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.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.19.UNRELEASED">(as a draft)</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
+ (Amount = 321, Scale = 2, Currency = "GBP"), but could be
+ represented by (Amount = 3210, Scale = 3, Currency = "GBP")
+ in a service that records balance in units of 0.001 pounds.</p>
+
+ <p>As a special case, if Amount = 0, Scale = 2**32 and Currency = "",
+ 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 Scale property; for instance, an Amount value of
+ 1234 with Scale of 2 represents 12.34 in the currency unit given
+ by the Currency.</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 Amount
+ property, 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 Amount, 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 international currency code represented by this amount, such
+ as "EUR", "USD", or "JPY". 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 Connection.
+ 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 is likely to have an unknown
+ value, represented by Amount = 0, Scale = 2**32 and
+ Currency = "".</p>
+
+ <p>On services where <tp:member-ref>ChangeNotification</tp:member-ref>
+ is FALSE, the value of this property contains the last known
+ balance, which will be unknown until a current balance has been
+ downloaded using <tp:member-ref>RequestBalance</tp:member-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="RequestBalance" tp:name-for-bindings="Request_Balance">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Get the current value of the balance, making a network request to
+ the server or waiting for a previous network request to complete
+ if necessary.</p>
+ </tp:docstring>
+
+ <arg name="Balance" direction="out"
+ type="(ius)" tp:type="Currency_Amount">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An up-to-date value of the balance.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Errors.Disconnected" />
+ <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable" />
+ </tp:possible-errors>
+ </method>
+
+ <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. On services
+ where <tp:member-ref>ChangeNotification</tp:member-ref> is FALSE,
+ this will only be emitted if a client calls
+ <tp:member-ref>RequestBalance</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Balance" type="(ius)" tp:type="Currency_Amount">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An up-to-date value of the balance.</p>
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="ChangeNotification"
+ tp:name-for-bindings="Change_Notification"
+ access="read" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If TRUE, clients can expect timely notification of
+ changes to the balance. If FALSE, the
+ <tp:member-ref>BalanceChanged</tp:member-ref> signal will not be
+ emitted unless
+ <tp:member-ref>RequestBalance</tp:member-ref> is called.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 1b970f6..499886d 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -42,6 +42,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Connection.xml"/>
<xi:include href="Connection_Interface_Aliasing.xml"/>
<xi:include href="Connection_Interface_Avatars.xml"/>
+ <xi:include href="Connection_Interface_Balance.xml"/>
<xi:include href="Connection_Interface_Capabilities.xml"/>
<xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
<xi:include href="Connection_Interface_Contact_Info.xml"/>
--
1.5.6.5
More information about the telepathy-commits
mailing list