Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit efbc20fe authored by Pankaj Kanwar's avatar Pankaj Kanwar Committed by Tyler Gunn
Browse files

Update USSD API docs per API review comments. 

Expand docs on failure return codes.
@hide the success return code which is only used internally.
Expand docs on the UssdResponseCallback class to make them more clear
what the format of the USSD response is, and how it might be consumed.
Fixed broken java doc.

Test: Make docs, inspect docs.
Bug: 35766890
Change-Id: I7a3c26c436c60372116c5b43cb45c513f4276b8c
parent 790ec07c

api/current.txt

+0 −1
Original line number Diff line number Diff line
@@ -40320,7 +40320,6 @@ package android.telephony { 
    field public static final int SIM_STATE_UNKNOWN = 0; // 0x0

    field public static final int USSD_ERROR_SERVICE_UNAVAIL = -2; // 0xfffffffe

    field public static final int USSD_RETURN_FAILURE = -1; // 0xffffffff

    field public static final int USSD_RETURN_SUCCESS = 100; // 0x64

    field public static final java.lang.String VVM_TYPE_CVVM = "vvm_type_cvvm";

    field public static final java.lang.String VVM_TYPE_OMTP = "vvm_type_omtp";

  }

api/system-current.txt

+0 −1
Original line number Diff line number Diff line
@@ -43860,7 +43860,6 @@ package android.telephony { 
    field public static final int SIM_STATE_UNKNOWN = 0; // 0x0

    field public static final int USSD_ERROR_SERVICE_UNAVAIL = -2; // 0xfffffffe

    field public static final int USSD_RETURN_FAILURE = -1; // 0xffffffff

    field public static final int USSD_RETURN_SUCCESS = 100; // 0x64

    field public static final java.lang.String VVM_TYPE_CVVM = "vvm_type_cvvm";

    field public static final java.lang.String VVM_TYPE_OMTP = "vvm_type_omtp";

  }

api/test-current.txt

+0 −1
Original line number Diff line number Diff line
@@ -40514,7 +40514,6 @@ package android.telephony { 
    field public static final int SIM_STATE_UNKNOWN = 0; // 0x0

    field public static final int USSD_ERROR_SERVICE_UNAVAIL = -2; // 0xfffffffe

    field public static final int USSD_RETURN_FAILURE = -1; // 0xffffffff

    field public static final int USSD_RETURN_SUCCESS = 100; // 0x64

    field public static final java.lang.String VVM_TYPE_CVVM = "vvm_type_cvvm";

    field public static final java.lang.String VVM_TYPE_OMTP = "vvm_type_omtp";

  }

telephony/java/android/telephony/TelephonyManager.java

+36 −16
Original line number Diff line number Diff line
@@ -883,16 +883,24 @@ public class TelephonyManager { 


    /**

     * USSD return code success.

     * @hide

     */

    public static final int USSD_RETURN_SUCCESS = 100;



    /**

     * USSD return code for failure case.

     * Failed code returned when the mobile network has failed to complete a USSD request.

     * <p>

     * Returned via {@link TelephonyManager.UssdResponseCallback#onReceiveUssdResponseFailed(

     * TelephonyManager, String, int)}.

     */

    public static final int USSD_RETURN_FAILURE = -1;



    /**

     * USSD return code for failure case.

     * Failure code returned when a USSD request has failed to execute because the Telephony

     * service is unavailable.

     * <p>

     * Returned via {@link TelephonyManager.UssdResponseCallback#onReceiveUssdResponseFailed(

     * TelephonyManager, String, int)}.

     */

    public static final int USSD_ERROR_SERVICE_UNAVAIL = -2;
@@ -5098,27 +5106,39 @@ public class TelephonyManager { 
        return new int[0];

    }



    /* The caller of {@link #sendUssdRequest(String, UssdResponseCallback, Handler} provides

     * once the network returns a USSD message or if there is failure.

     * Either {@link #onReceiveUssdResponse(TelephonyManager, String, CharSequence} or

     * {@link #onReceiveUssdResponseFailed(TelephonyManager, String, int} will be called.

    /**

     * Used to notify callers of

     * {@link TelephonyManager#sendUssdRequest(String, UssdResponseCallback, Handler)} when the

     * network either successfully executes a USSD request, or if there was a failure while

     * executing the request.

     * <p>

     * {@link #onReceiveUssdResponse(TelephonyManager, String, CharSequence)} will be called if the

     * USSD request has succeeded.

     * {@link #onReceiveUssdResponseFailed(TelephonyManager, String, int)} will be called if the

     * USSD request has failed.

     */

    public static abstract class UssdResponseCallback {

       /**

        * Called when USSD has succeeded. The calling app can choose to either display the message

        * or interpret the message.

        * Called when a USSD request has succeeded.  The {@code response} contains the USSD

        * response received from the network.  The calling app can choose to either display the

        * response to the user or perform some operation based on the response.

        * <p>

        * USSD responses are unstructured text and their content is determined by the mobile network

        * operator.

        *

        * @param telephonyManager the TelephonyManager the callback is registered to.

        * @param request the ussd code sent to the network.

        * @param response the response from the network.

        * @param request the USSD request sent to the mobile network.

        * @param response the response to the USSD request provided by the mobile network.

        **/

       public void onReceiveUssdResponse(final TelephonyManager telephonyManager,

                                         String request, CharSequence response) {};



       /**

        * Called when USSD has failed.

        * @param telephonyManager the TelephonyManager the callback is registered to

        * @param request the ussd code.

        * @param failureCode failure code, should be either of

        * Called when a USSD request has failed to complete.

        *

        * @param telephonyManager the TelephonyManager the callback is registered to.

        * @param request the USSD request sent to the mobile network.

        * @param failureCode failure code indicating why the request failed.  Will be either

        *        {@link TelephonyManager#USSD_RETURN_FAILURE} or

        *        {@link TelephonyManager#USSD_ERROR_SERVICE_UNAVAIL}.

        **/
@@ -5127,8 +5147,8 @@ public class TelephonyManager { 
    }



    /**

     * Sends an Unstructured Supplementary Service Data (USSD) request to the cellular network and

     * informs the caller of the response via {@code callback}.

     * Sends an Unstructured Supplementary Service Data (USSD) request to the mobile network and

     * informs the caller of the response via the supplied {@code callback}.

     * <p>Carriers define USSD codes which can be sent by the user to request information such as

     * the user's current data balance or minutes balance.

     * <p>Requires permission: