Bug 24903

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.

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.

(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.

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

Note that the amount value is signed, to be able to report negative balances as well.

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?

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.

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

(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.

(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.

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

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.

(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.

Fixed in git, will be in 0.19.0

(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.