Bug 24903

Summary: Balance (credit info) interface
Product: Telepathy Reporter: Simon McVittie <smcv>
Component: tp-specAssignee: Telepathy bugs list <telepathy-bugs>
Status: RESOLVED FIXED QA Contact: Telepathy bugs list <telepathy-bugs>
Severity: enhancement    
Priority: low CC: mikhail.zabaluev
Version: unspecifiedKeywords: patch
Hardware: Other   
OS: All   
URL: http://git.collabora.co.uk/?p=user/smcv/telepathy-spec-smcv.git;a=shortlog;h=refs/heads/balance-stable
Whiteboard: draft should land in 0.19.0; spec cabal review needed
i915 platform: i915 features:
Bug Depends on:    
Bug Blocks: 24894, 25302    

Description Simon McVittie 2009-11-04 05:59:35 UTC
Maemo 5 uses various extended interfaces beyond what's in telepathy-spec. One such interface is an API for credit info, compatible with Skype:

http://git.collabora.co.uk/?p=rtcom-telepathy-glib.git;a=blob;f=rtcom-telepathy-glib/Connection_Interface_Skype_CreditInfo.xml

We should merge this functionality into the main telepathy-spec, after generalizing it to other protocols. I suspect there's a SIP RFC for this :-)
Comment 1 Simon McVittie 2009-11-05 04:17:18 UTC
I can't find a SIP RFC for this, although one RFC suggests that INFO messages can be used (in an unspecified way, so presumably not machine-readably) for balance information. Text of the Maemo interface follows:

This interface extends the core Connection interface to provide credit balance information.

As an example, property values of Balance=1234, BalanceScale=2 and Currency=USD, can be used by UI to format the credit display like
"12.34 USD".

readable property Balance : u
    Expressed as a fixed point number with decimal scale defined by the
    BalanceScale property.
    E.g. a Balance value of 1234 with BalanceScale of 2 represents 12.34
    in the currency unit given by the value Currency.

readable property Currency : s
    Currency string that should be used when displaying balance in three
    letter currecy code. E.g. "EUR", "USD", or "JPY".

readable property BalanceScale : u
    The decimal scale for the fixed point value of the Balance property,
    defining the number of rightmost decimal digits from the integer
    value, which form the fractional part of the resulting currently value.

signal BalanceChanged : u, u, s
    Emitted when the balance changes. All properties are provided as
    arguments.

    Balance : u
    BalanceScale : u
    Currency : s

With some editorial changes, this interface looks fine to me.
Comment 2 Simon McVittie 2009-11-05 06:35:18 UTC
Mikhail tells me there have been API changes in this interface. Mikhail, could you update us?

Un-keywording til we can see the current situation.
Comment 3 Mikhail Zabaluev 2009-11-05 06:37:53 UTC
(In reply to comment #2)
> Mikhail tells me there have been API changes in this interface. Mikhail, could
> you update us?

Yes, we have created a structure data type out of the three values and renamed the interface, due to appear in an updated version of librtcom-telepathy-glib.
If it migrates into a Telepathy draft, we can ship that instead.
Comment 4 Mikhail Zabaluev 2009-11-05 06:48:38 UTC
The structure is defined as follows:

    <tp:struct name="Currency_Amount"
	       array-name="Currency_Amount_Struct">
      <tp:member type="i" name="Amount">
	<tp:docstring>
	  Expressed as a fixed point number with decimal scale defined by the
	  Scale property.
	  E.g. a Amount value of 1234 with Scale of 2 represents 12.34
	  in the currency unit given by the value Currency.
	</tp:docstring>
      </tp:member>
      <tp:member type="u" name="Scale">
	<tp:docstring>
	  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 currently
	  value.
	</tp:docstring>
      </tp:member>
      <tp:member type="s" name="Currency">
	<tp:docstring>
	  Currency string that should be used when displaying amount.
	  E.g. "EUR", "USD", or "JPY".
	</tp:docstring>
      </tp:member>
    </tp:struct>

The interface members now look as follows:

readable property AccountBalance: CurrencyAmount

signal BalanceChanged: CurrencyAmount
Comment 5 Mikhail Zabaluev 2009-11-05 06:52:31 UTC
Note that the amount value is signed, to be able to report negative balances as well.
Comment 6 Simon McVittie 2009-11-05 10:07:00 UTC
The spec cabal likes it. I'll get it XML'd up tomorrow, and try to do a spec release with it as a draft tomorrow or next week.

If you have already implemented this and are sufficiently sure that it's right, we could skip the draft stage (which you essentially did internally) and go straight to the final namespace?
Comment 7 Simon McVittie 2009-11-06 12:06:32 UTC
While drafting the markup, I realised that the interface as written doesn't support services where you have to poll for the balance (I'm sure they exist, sadly), so I added some support for those.

I also added a representation for "I don't know what the balance is" (balance 0, scale uint32max and currency "", as suggested by the spec cabal), added a representation for "the service didn't tell us the currency" (empty string), and did some editorial tweaks.
Comment 9 Mikhail Zabaluev 2009-11-12 07:31:31 UTC
(In reply to comment #8)
> http://people.freedesktop.org/~smcv/telepathy-spec-balance/spec/org.freedesktop.Telepathy.Connection.Interface.Balance.DRAFT.html

Looks comprehensive. I'd relax the definition of Currency as "international currency code": I've seen Skype giving its own pseudo units.
Comment 10 Simon McVittie 2009-11-12 08:06:48 UTC
(In reply to comment #9)
> 
> I'd relax the definition of Currency as "international
> currency code": I've seen Skype giving its own pseudo units.

Sad face. OK, I'll relax that to "SHOULD be an international currency code".

What pseudo-units does Skype use? If there's a finite set, we could define a pseudo-currency-code for them ("x-skype-credits" or something?), or at least have Skype connection managers override the currency to "" for them.
Comment 11 Simon McVittie 2009-11-26 07:50:07 UTC
Spec updated:

http://people.freedesktop.org/~smcv/telepathy-spec-balance/spec/org.freedesktop.Telepathy.Connection.Interface.Balance.DRAFT.html

Following discussion in the office I've reverted support for poll-only protocols: if we encounter such a protocol, the CM should emulate a protocol with change notification, by polling once on startup and once at the end of each call.

I'd like to have this in telepathy-spec 0.19.0, at least as a draft; we can sync it into librtcom-telepathy-glib for use in Maemo.

If you (Mikhail and Naveen) are confident that this API will only change in compatible ways in future, we could give it stable status straight away; it's up to you. If so, we'd merge one additional commit:

http://git.collabora.co.uk/?p=user/smcv/telepathy-spec-smcv.git;a=shortlog;h=refs/heads/balance-stable
Comment 12 Mikhail Zabaluev 2009-11-27 10:14:36 UTC
I can't understand how do you represent Scale = 2**32 as a D-Bus unsigned integer.
Aside from this, I'm confident that the API can be declared stable for our purposes.
Comment 13 Simon McVittie 2009-11-30 08:54:12 UTC
(In reply to comment #12)
> I can't understand how do you represent Scale = 2**32 as a D-Bus unsigned
> integer.

Oops, I meant 2**32 - 1; balance-stable branch updated.
Comment 14 Simon McVittie 2009-11-30 09:30:07 UTC
Fixed in git, will be in 0.19.0
Comment 15 Mikhail Zabaluev 2009-12-11 09:49:09 UTC
(In reply to comment #13)
> Oops, I meant 2**32 - 1; balance-stable branch updated.

It's more dangerous than strictly necessary, because naive code could try to allocate a string of necessary length to accommodate the precision, without checking if the precision is sane. In case the value is not set, such allocation will fail.

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.