Re: USSD interface for ModemManager

[Dan Williams <dcbw redhat com>]

On Tue, 2010-03-09 at 13:45 +0100, Pablo Martí Gamboa wrote:
> Hi Dan, Marcel and others,
> 
> 
> we would like to extend the ModemManager API so that it can handle
> USSD commands. The USSD API of oFono [0] looks quite nice IMHO and I'd
> like to propose a similar API:

I'd actually change two things; this API (and by extension the ofono
one) doesn't allow clients to respond to a USSD request that is pending
when they start up.  Say your app sends the request, then crashes or
something.  When it's crashed, the network sends the response.  Now your
app can't get the response when it starts back up and handle it, it
would have to cancel the USSD session and send the request again.

A more robust API would change the NotificationReceived and
RequestReceived signals into properties instead, which can be queried
when your app starts up.  See below...

I did add a org.freedesktop.DBus.Properties.MmPropertiesChanged signal
to ModemManager a bit ago, mainly to support the
org.freedesktop.ModemManager.Modem.Enabled property.  So we can
certainly use that.

> 
> USSD Interface
> ===============
> 
> 
> Service org.freedesktop.ModemManager
> Interface         org.freedesktop.ModemManager.Modem.Gsm.Ussd
> 
> 
> Methods string Initiate(string command)
> 
> 
> Sends a USSD command string to the network
> initiating a session.  When the request is handled
> by the appropriate node of the network, the
> method returns the response or an appropriate
> error.  The network may be awaiting further response
> from the ME after returning from this method and no
> new command can be initiated until this one is
> cancelled or ended.
> 
> 
> void Respond(string reply)
> 
> 
> Send a response to the network either when
> it is awaiting further input after Initiate()
> was called or after a network-initiated request.
> 
> 
> void Cancel()
> 
> 
> Cancel an ongoing USSD session, mobile- or
> network-initiated.
> 
> 
> Signals 
>                 NotificationReceived(string message)

I would change this to a read-only "NetworkNotification" property, and
then we can use the normal D-Bus properties API to get it, and the
MmPropertiesChanged signal to notify when it changes.

> 
> Signal is emitted on a network-initiated USSD
> request for which no response is needed.
> 
> 
> RequestReceived(string message)

Same here, I'd suggest a read-only "NetworkRequest" property.

Obviously when there is no request from the network, these two
properties would be empty strings.

Any thoughts on this?

Dan

> 
> Signal is emitted on a network-initiated USSD
> request for which a response must be sent using
> the Respond method unless it is cancelled or
> the request is not supported.
> 
> 
> Properties string State [readonly]
> 
> 
> Reflects the state of current USSD session.  The
> values have the following meanings:
> 
> 
> "idle" No active USSD session.
> "active" A session is active between the
> network and the ME, the ME is
> waiting for a reply from the
> network.
> "user-response" The network is waiting for the
> user's response, client must
> call Respond().
> 
> 
> 
> 
> It is basically a copy of their API (they nailed it down) except for
> GetProperties and PropertiesChanged signal which are ConnMan-specific.
> I haven't had a use-case yet for the "Respond" command (my USSD
> petitions are simple), but it needs to be there indeed for future
> uses. Thoughts?
> 
> 
> [0] http://git.kernel.org/?p=network/ofono/ofono.git;a=blob_plain;f=doc/supplementaryservices-api.txt;hb=HEAD
> 
> -- 
> Pablo Martí
> http://www.linkedin.com/in/pmarti || http://www.warp.es
> python -c "print '706d6172746940776172702e6573'.decode('hex')"
> 
>