Merge "Update docs and ensure PHONE_STATE is more predictable for unknown numbers." into pi-dev

        // Wakeup apps for the (SUBSCRIPTION_)PHONE_STATE broadcast.

        intent.addFlags(Intent.FLAG_RECEIVER_INCLUDE_BACKGROUND);

        // Create a version of the intent with the number always populated.

        Intent intentWithPhoneNumber = new Intent(intent);

        if (!TextUtils.isEmpty(incomingNumber)) {

        intentWithPhoneNumber.putExtra(TelephonyManager.EXTRA_INCOMING_NUMBER, incomingNumber);

        }

        // Send broadcast twice, once for apps that have PRIVILEGED permission and once for those

        // that have the runtime one

        mContext.sendBroadcastAsUser(intentWithPhoneNumber, UserHandle.ALL,

     * <p>

     * The {@link #EXTRA_STATE} extra indicates the new call state.

     * If a receiving app has {@link android.Manifest.permission#READ_CALL_LOG} permission, a second

     * extra {@link #EXTRA_INCOMING_NUMBER} provides the phone number for incoming and outoing calls

     * as a String.  Note: If the receiving app has

     * extra {@link #EXTRA_INCOMING_NUMBER} provides the phone number for incoming and outgoing

     * calls as a String.

     * <p>

     * If the receiving app has

     * {@link android.Manifest.permission#READ_CALL_LOG} and

     * {@link android.Manifest.permission#READ_PHONE_STATE} permission, it will receive the

     * broadcast twice; one with the phone number and another without it.

     * broadcast twice; one with the {@link #EXTRA_INCOMING_NUMBER} populated with the phone number,

     * and another with it blank.  Due to the nature of broadcasts, you cannot assume the order

     * in which these broadcasts will arrive, however you are guaranteed to receive two in this

     * case.  Apps which are interested in the {@link #EXTRA_INCOMING_NUMBER} can ignore the

     * broadcasts where {@link #EXTRA_INCOMING_NUMBER} is not present in the extras (e.g. where

     * {@link Intent#hasExtra(String)} returns {@code false}).

     * <p class="note">

     * This was a {@link android.content.Context#sendStickyBroadcast sticky}

     * broadcast in version 1.0, but it is no longer sticky.

    public static final String EXTRA_STATE_OFFHOOK = PhoneConstants.State.OFFHOOK.toString();

    /**

     * The lookup key used with the {@link #ACTION_PHONE_STATE_CHANGED} broadcast

     * for a String containing the incoming phone number.

     * Only valid when the new call state is RINGING.

     *

     * Extra key used with the {@link #ACTION_PHONE_STATE_CHANGED} broadcast

     * for a String containing the incoming or outgoing phone number.

     * <p>

     * This extra is only populated for receivers of the {@link #ACTION_PHONE_STATE_CHANGED}

     * broadcast which have been granted the {@link android.Manifest.permission#READ_CALL_LOG} and

     * {@link android.Manifest.permission#READ_PHONE_STATE} permissions.

     * <p>

     * For incoming calls, the phone number is only guaranteed to be populated when the

     * {@link #EXTRA_STATE} changes from {@link #EXTRA_STATE_IDLE} to {@link #EXTRA_STATE_RINGING}.

     * If the incoming caller is from an unknown number, the extra will be populated with an empty

     * string.

     * For outgoing calls, the phone number is only guaranteed to be populated when the

     * {@link #EXTRA_STATE} changes from {@link #EXTRA_STATE_IDLE} to {@link #EXTRA_STATE_OFFHOOK}.

     * <p class="note">

     * Retrieve with

     * {@link android.content.Intent#getStringExtra(String)}.