Provision of USSD API support

[milind....@sasken.com]

Sasken proposes to contribute following USSD API enhancements to the
android open source project.

- Support for sending of USSD message
- Support for receiving of USSD Notify/ Response

This requirement essentially arises from an enhancement request
#1285.

http://code.google.com/p/android/issues/detail?id=1285

The changes to the framework are described below. Before starting with
the design and implementation, we would like to have some feedback on
our proposal.

====================
ARCHITECTURAL IMPACT
====================

Current implementation provides the USSD functionality as a normal
dial transaction. Thus the USSD string is sent by the dialer using the
dial intent to the framework. The dialed string is then parsed by the
dial string parser and if found to be a USSD string, invokes the USSD
session.

Following are the details of the current implementation:

Currently USSD handling is being performed by the class "GsmMMICode"
which parses the dial string through the GsmMMICode.process Code and
invokes the USSD transaction.

The response / notification received for this request is also sent to
the Dial MMI .

Thus in case there is a user application which wants to use the USSD
session for sending and receiving strings, currently there is no API
available for USSD transactions for it to use.

The proposed feature enhancement is to provide a USSD send and receive
facility to the user application without binding to the phone dial
code functionality.


Changes are required only in the Telephony Framework. No changes are
required in the RIL.

----------------------
Change details
-----------------------

UssdManager
--------------------

New class UssdManager will have to be introduced which would expose
following APIs to enable the Application to send, receive and cancel
of USSD transactions .

USSD notifier registration/unregister functions for application to
register for USSD events
- registerForUssdNotification
- unregisterForUssdNotification


NOTE: In this case the use application can implement the callback
registration and handling similar to existing apps like
EmergencyCallHandler and BluetoothHandsFree which are registered for
handling SERVICE_STATE_CHANGED message from the framework.

USSD Send API - sendAppUssd(String ussdMessage) can be provided. The
App Ussd session would be identified using the isAppUSSDPending flag
which would help identify the App Ussd session from the Phone MMI ussd
session.

USSD Cancel API - cancelAppUssd() can be provided for cancelling a App
ussd session in progress.

App USSD Error handler - for sending Ussd error information to App
which had invoked the ussd transaction.
onAppUssdFinishedError to be provided for notifying the App registrant
about the occurrence of an error.

App USSD Finished handler - for sending ussd success information to
App which had invoked the ussd transaction.
onAppUssdFinished be provided for notifying the app registrant about a
ussd response or ussd notification which can be handled by the App
appropriately.


GsmPhone
------------------

The incoming USSD callback handler in class “GsmPhone” is currently
implemented to route the USSD response/notifications to the USSD MMI.
In order to ensure that the response is routed to the USSD
Application, it would be required to check whether the response is in
relation to an Application initiated or Dial initiated USSD session.

If it is established that the session in progress is an Application
initated session, the response would be routed to the USSD
Application.


In case of a network initiated USSD handling, the USSD Application of
interest should be registered with the framework. Any network
initiated USSD would then be handled in the USSD callback handler and
routed to the USSD application. In absence of any application being
registered for receiving network initiated USSD, the USSD message
would be routed to the default USSD MMI.

Described below are the implementation details :

Modify onIncomingUSSD callback function to invoke the app ussd
handlers in case of USSD operations was invoked using the Send USSD
API

Check to be added in the onIncomingUSSD handler for verifying whether
USSD response/notification is pending (isUSSDPending).

Depending on the whether we have a registered for USSD session or
not the ussd response would be routed to the USSD or to the
GsmMMICode handlers.

Support for handling network initiated USSD for s registered for
receiving these events.

If a is registered for receiving the Network initiated USSD , it can
be identified using the mAppUssdRegistrants.size value

Based on this check and no ussd is pending, the USSD event can be
routed to the onNetworkInitiatedUssd for the registered to handled
else it could be routed to the GsmMMICode handler.

[staropram]

This is a brilliant idea, and it is great that you are proposing this contribution.

I can only hope Google takes this proposition on.

You could start the implementation, but without knowing what Google is doing on this issue, it would be a gamble.

staropram

[John Huang]

Hi Milind,

Thank you for the proposal. Please upload your changes to
https://review.source.android.com.

A few quick comments/questions:
- It seems like the usefulness of these APIs would be limited to
carrier provided apps (or at least apps targeted for specific
carriers), since USSD by nature is carrier specific. Not that we
shouldn't add these APIs because of that - I'm just wondering if I'm
missing a more general usage.

- Would an application be able to handle network-initiated USSD? How
would that work?

Thanks.
-john

On Mar 8, 7:19 am, "milind.nadka...@sasken.com"

[milind....@sasken.com]

Hi John
Appreciate your response.

Following are the answers to your queries:
1.API Utility - USSD strings are indeed carrier specific. Every
carrier provides a certain set of USSD strings for performing various
transactions like balance enquiry, service registrations etc.

The utility of this API is that it provides the application developer
the means to utilize the USSD transactions as a means of invoking
these operator services.
e.g. There are instances of gaming platforms which use USSD for
getting information like High scores, User Lists etc.from their
servers. An API of this form would be of great utility to such
requirements.

In order to address the issue of a different set of USSD strings for
every operator, the application can be made configurable by defining
set of xml values for every carrier type.
Depending on the available carrier type, the appropriate USSD strings
could be applied from the xml string set.

2. Network Initiated USSD handling - Since the focus of the proposed
solution was to provide the user an API for invoking USSD
transactions, in order to handle the network initiated USSD , the
application would be required to be listening on network initiated
USSD events. So currently there is a limitation in this regard that
the application would need to be in context in order to receive any
network initiated event.
However, this can be improved later on to do away with this current
limitation.

On Apr 6, 9:54 pm, John Huang <j...@android.com> wrote:
> Hi Milind,
>

> Thank you for the proposal.  Please upload your changes tohttps://review.source.android.com.

[Todd]

Another angle on USSD is when you're roaming, the current serving
network should pass unrecognized USSD string requests from the mobile
back to your home network for processing.

Todd

On Apr 7, 2:32 am, "milind.nadka...@sasken.com"

[Cuihtlauac]

Hi,

Was anything uploaded to https://review.source.android.com on this ? I can't find.

[Milind]

Hi,
Currently this activity is in the testing/debugging phase. As soon as
this is completed we plan to submit for review.

Regards
Milind Nadkarni

On Jul 7, 1:05 pm, Cuihtlauac <cuihtlauac.alvar...@orange-ftgroup.com>
wrote:
> Hi,
>
> Was anything uploaded tohttps://review.source.android.comon this ? I can't
> find.

[Cuihtlauac ALVARADO]

Hi

I've uploaded two patches exposing a (soft) USSD API:

https://review.source.android.com/24548
https://review.source.android.com/24549

The approach is not the one proposed by Milind. It's entirely Intent based:

Intent.ACTION_USSD_RESPONSE

Is used in startService() with a tel: URI argument containing the USSD
number. This intent is silently discarded when the Phone application is
displayed.

Intent.ACTION_USSD_REQUEST_OR_NOTIFY

Is broadcast by the system (actually, the Phone application) when an
USSD message is received. The USSD message text goes with EXTRA_TEXT.
This intent is silently not sent when the phone application is displayed.

Overall, the idea is to continue to have the Phone application in charge
of handling USSD messages. When it is displayed, request to have USSD
messages sent are discarded and incoming USSD messages are displayed to
the user. It is only when the Phone application is not displayed that
those intents are accepted or broadcast.

Additionally, there are no mean to known a REQUEST_OR_NOTIFY is a
'response' to a RESPONSE. That's on purpose. Allows an uniform handling
of mobile initiated and network initiated USSD.

[RoyWanyaga]

Hi Cuihtlauac, I am a developer interested in android..In the post above you indicated in some two links with the proposed (soft) USSD API but they are not available. I am trying to develop a USSD application for the blind so I have to capture the USSD response and pass it through a tts.. this is not possible currently because I cannot capture the mmi display.. On this particular issue, and many others the USSD API would be greatly essential. Thanks.

[Cuihtlauac ALVARADO]

Hi Roy,

The initial patch set go lost during the AOSP downtime. I've ported it from Gingerbread to ICS and submitted it:

https://android-review.googlesource.com/35810

It's slightly changed (improved ?), the intents are now called: 

android.intent.action.ussd.SEND

android.intent.action.ussd.RECEIVE

Feedback welcome

[游士杰]

[Jake Hamby]

Hi Roy,

I'm an engineer on the Android telephony team, and USSD is one of the features that I support. I just tested a USSD request with TalkBalk enabled and verified that the USSD response in the alert dialog is not being spoken. That's a bug on our part, and I just created an internal bug report to fix it in the platform. You shouldn't have to write your own app because our accessibility support isn't doing the right thing.

BTW, there's a great Google I/O talk from last year about how to enable your own apps for accessibility support. For your GUI elements, when the default TTS isn't the correct behavior, you can add a single method, dispatchPopulateAccessibilityEvent(), which passes an AccessibilityEvent parameter. Call getText() on the event to get the List<CharSequence> of strings to be spoken, and then add your text to the list. You can also pass the AccessibilityEvent to the dispatchPopulateAccessibilityEvent in your child views.

http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html

Here's the Google I/O talk:

http://www.youtube.com/watch?v=BPXqsPeCneA

Here's an example from the emergency warning cell broadcast app located at packages/apps/CellBroadcastReceiver/src/com/android/cellbroadcastreceiver/CellBroadcastListItem.java, which I added to speak the alert components in the correct order:

    @Override

    public boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event) {

        // Speak the date first, then channel name, then message body

        event.getText().add(mCbMessage.getSpokenDateString(getContext()));

        mChannelView.dispatchPopulateAccessibilityEvent(event);

        mMessageView.dispatchPopulateAccessibilityEvent(event);

        return true;

    }

So if you're interested in improving the accessibility of the platform, please consider submitting patches to add these accessibility hooks in the places where the default behavior isn't correct (or file bugs if you notice something broken and don't have the resources to fix it yourself).

I haven't reviewed the USSD API patches that Cuihtlauac submitted yet, so I'll comment on those in gerrit when I have time. I know there's at least one operator that has a proprietary APK that manages USSD requests and responses for their network, so I'll find out what hooks they're using and figure out what makes the most sense for the platform. Thanks for the submission!

Regards,

Jake

[Jignesh Kakkad(Jiggy)]

Hi Guys,

I am also working on USSD part (but not in Android's USSD API).

Is there any sample application or example of Android USSD API?

Thanks

Regards

Jiggy

[Cuihtlauac ALVARADO]

Hi Jignesh,

The patch I submitted allows to write things like that, for sending:

Intent send = new Intent("android.intent.action.ussd.SEND", Uri.fromParts("tel", "#123#", null));

this.startService(intent);

and receiving:

receiver = new BroadcastReceiver() {

    @Override

    public void onReceive(Context ctx, Intent i) {

        if (i.getAction().equals("android.intent.action.ussd.RECEIVE")) {

            CharSequence text = (CharSequence) i.getStringExtra(Intent.EXTRA_TEXT);

            // blah blah blah...

        }

    }

}

IntentFilter filter = new android.content.IntentFilter();

filter.addAction(ussdReceive, "android.intent.action.ussd.RECEIVE");

this.registerReceiver(receiver, filter);

    

 Regards

[malik Mudassar]

Hi Cuihtlauac ALVARADO,
I am an android developer & am looking into telephony API's these days. I am trying to make an app for network operator that use callback using ussd commands. So for what I have learned is we can process a ussd command using highl level android api's using Intent.action_call but we cannot get the response.
So can you briefly explain how your patch works?
How can I used it? It seems you have modified PhoneApp.java class, In which build it would be incoprated or I can use the patch in any SDK.
One thing more, can you please give some more description about the patch your have wrote, how it works etc.
Regards
mAlik

[malik Mudassar]

Can you please some more description of your patch? How can we use it in our app etc?

[Matt Searle]

Hi,

I am a very new Android developer and I am currently trying to build an app which needs to be able to send USSD messages but I am having trouble understanding how to implement this patch and what I need to do to in order to implement something like your example:

Intent send = new Intent("android.intent.action.ussd.SEND", Uri.fromParts("tel", "#123#", null));

this.startService(intent);

Could you possibly walk me through how this works and how to implement your patch?

Thank you

[Daniel Keller]

I am pretty new myself problem kinda sounds like you are trying to great a worm or something like a Trojan so you may want to revise you're term I not sure what USSD messages stands for but the intent just might be that you are throwing Android develiopers off.Are you trying to great a remote access to use on other computers??

                                                                 1Hillbilly2011

--
 
---
You received this message because you are subscribed to the Google Groups "Android Contributors" group.
To unsubscribe from this group and stop receiving emails from it, send an email to android-contr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Matt Searle]

I'm not in anyway trying to create a worm. The app I am creating is simply trying to use USSD to send a data update from the phone to my network provider who then forwards that data on to my web server. I would like to do this in the background while using the app.

[Jean-Baptiste Queru]

Let's please get this discussion back on track, i.e. about contributing a change to AOSP.

Thanks,

JBQ

--
Jean-Baptiste M. "JBQ" Queru
Technical Lead, Android Open Source Project, Google.

Questions sent directly to me that have no reason for being private will likely get ignored or forwarded to a public forum with no further warning.

[Matt Searle]

As a new Android developer looking to use this patch:

https://android-review.googlesource.com/35810

how do I go about adding including it in my project?

[Jean-Baptiste Queru]

You can't. This is an OS-level patch, which is the topic of this Google Group.

JBQ