diff options
Diffstat (limited to 'spec/spec/Connection_Interface_Balance.xml')
| -rw-r--r-- | spec/spec/Connection_Interface_Balance.xml | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/spec/spec/Connection_Interface_Balance.xml b/spec/spec/Connection_Interface_Balance.xml new file mode 100644 index 000000000..974c651fd --- /dev/null +++ b/spec/spec/Connection_Interface_Balance.xml @@ -0,0 +1,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: --> |