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

Commit c8fa4ff8 authored by Jaikumar Ganesh's avatar Jaikumar Ganesh
Browse files

Improve readability of java docs for the public APIs. 

Change-Id: I0a0f1be04ed2ea2c14498a1a2ed4b050191ec95b
parent d63219f6

core/java/android/bluetooth/BluetoothA2dp.java

+17 −10
Original line number Diff line number Diff line
@@ -50,15 +50,18 @@ public final class BluetoothA2dp implements BluetoothProfile { 
     * profile.

     *

     * <p>This intent will have 3 extras:

     * {@link #EXTRA_STATE} - The current state of the profile.

     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile

     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.

     * <ul>

     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>

     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile.</li>

     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. </li>

     * </ul>

     *

     * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of

     * {@link #STATE_DISCONNECTED}, {@link #STATE_CONNECTING},

     * {@link #STATE_CONNECTED}, {@link #STATE_DISCONNECTING}.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission to

     * receive.

     */

    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)

    public static final String ACTION_CONNECTION_STATE_CHANGED =
@@ -69,14 +72,17 @@ public final class BluetoothA2dp implements BluetoothProfile { 
     * profile.

     *

     * <p>This intent will have 3 extras:

     * {@link #EXTRA_STATE} - The current state of the profile.

     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile

     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.

     * <ul>

     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>

     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile. </li>

     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. <li/>

     * </ul>

     *

     * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of

     * {@link #STATE_PLAYING}, {@link #STATE_NOT_PLAYING},

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission to

     * receive.

     */

    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)

    public static final String ACTION_PLAYING_STATE_CHANGED =
@@ -258,7 +264,7 @@ public final class BluetoothA2dp implements BluetoothProfile { 
    /**

     * Check if A2DP profile is streaming music.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.

     *

     * @param device BluetoothDevice device

     */
@@ -281,11 +287,12 @@ public final class BluetoothA2dp implements BluetoothProfile { 
     *

     * <p> This API will return false in scenarios like the A2DP

     * device is not in connected state etc. When this API returns,

     * true, it is guaranteed that {@link #ACTION_SINK_STATE_CHANGED}

     * true, it is guaranteed that {@link #ACTION_CONNECTION_STATE_CHANGED}

     * intent will be broadcasted with the state. Users can get the

     * state of the A2DP device from this intent.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}

     * permission.

     *

     * @param device Remote A2DP sink

     * @return false on immediate error,

core/java/android/bluetooth/BluetoothDevice.java

+18 −0
Original line number Diff line number Diff line
@@ -748,6 +748,15 @@ public final class BluetoothDevice implements Parcelable { 
     * outgoing connection to this remote device on given channel.

     * <p>The remote device will be authenticated and communication on this

     * socket will be encrypted.

     * <p> Use this socket only if an authenticated socket link is possible.

     * Authentication refers to the authentication of the link key to

     * prevent man-in-the-middle type of attacks.

     * For example, for Bluetooth 2.1 devices, if any of the devices does not

     * have an input and output capability or just has the ability to

     * display a numeric key, a secure socket connection is not possible.

     * In such a case, use {#link createInsecureRfcommSocket}.

     * For more details, refer to the Security Model section 5.2 (vol 3) of

     * Bluetooth Core Specification version 2.1 + EDR.

     * <p>Use {@link BluetoothSocket#connect} to initiate the outgoing

     * connection.

     * <p>Valid RFCOMM channels are in range 1 to 30.
@@ -775,6 +784,15 @@ public final class BluetoothDevice implements Parcelable { 
     * determine which channel to connect to.

     * <p>The remote device will be authenticated and communication on this

     * socket will be encrypted.

     * <p> Use this socket only if an authenticated socket link is possible.

     * Authentication refers to the authentication of the link key to

     * prevent man-in-the-middle type of attacks.

     * For example, for Bluetooth 2.1 devices, if any of the devices does not

     * have an input and output capability or just has the ability to

     * display a numeric key, a secure socket connection is not possible.

     * In such a case, use {#link createInsecureRfcommSocketToServiceRecord}.

     * For more details, refer to the Security Model section 5.2 (vol 3) of

     * Bluetooth Core Specification version 2.1 + EDR.

     * <p>Hint: If you are connecting to a Bluetooth serial board then try

     * using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB.

     * However if you are connecting to an Android peer then please generate

core/java/android/bluetooth/BluetoothHeadset.java

+38 −30
Original line number Diff line number Diff line
@@ -52,15 +52,17 @@ public final class BluetoothHeadset implements BluetoothProfile { 
     * profile.

     *

     * <p>This intent will have 3 extras:

     * {@link #EXTRA_STATE} - The current state of the profile.

     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile

     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.

     *

     * <ul>

     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>

     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile. </li>

     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. </li>

     * </ul>

     * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of

     * {@link #STATE_DISCONNECTED}, {@link #STATE_CONNECTING},

     * {@link #STATE_CONNECTED}, {@link #STATE_DISCONNECTING}.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission to

     * receive.

     */

    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)

    public static final String ACTION_CONNECTION_STATE_CHANGED =
@@ -71,14 +73,16 @@ public final class BluetoothHeadset implements BluetoothProfile { 
     * A2DP profile.

     *

     * <p>This intent will have 3 extras:

     * {@link #EXTRA_STATE} - The current state of the profile.

     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile

     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.

     *

     * <ul>

     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>

     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile. </li>

     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. </li>

     * </ul>

     * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of

     * {@link #STATE_AUDIO_CONNECTED}, {@link #STATE_AUDIO_DISCONNECTED},

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission

     * to receive.

     */

    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)

    public static final String ACTION_AUDIO_STATE_CHANGED =
@@ -90,16 +94,18 @@ public final class BluetoothHeadset implements BluetoothProfile { 
     * vendor-specific event.

     *

     * <p>This intent will have 4 extras and 1 category.

     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote Bluetooth Device

     * {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD} - The vendor specific

     *                                                    command

     * {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE} - The AT command

     *                                                         type.

     * Can be one of  {@link #AT_CMD_TYPE_READ}, {@link #AT_CMD_TYPE_TEST},

     * or {@link #AT_CMD_TYPE_SET}, {@link #AT_CMD_TYPE_BASIC},

     * {@link #AT_CMD_TYPE_ACTION}.

     *

     * {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS} - Command arguments.

     * <ul>

     *  <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote Bluetooth Device

     *       </li>

     *  <li> {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD} - The vendor

     *       specific command </li>

     *  <li> {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE} - The AT

     *       command type which can be one of  {@link #AT_CMD_TYPE_READ},

     *       {@link #AT_CMD_TYPE_TEST}, or {@link #AT_CMD_TYPE_SET},

     *       {@link #AT_CMD_TYPE_BASIC},{@link #AT_CMD_TYPE_ACTION}. <li/>

     *  <li> {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS} - Command

     *       arguments. </li>

     * </ul>

     *

     * The category is the Company ID of the vendor defining the

     * vendor-specific command. {@link BluetoothAssignedNumbers}
@@ -108,11 +114,13 @@ public final class BluetoothHeadset implements BluetoothProfile { 
     * Category will be {@link #VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY}.55

     *

     * <p> For example, an AT+XEVENT=foo,3 will get translated into

     * EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD = +XEVENT

     * EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE = AT_CMD_TYPE_SET

     * EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS = foo, 3

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.

     * <ul>

     *   <li> EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD = +XEVENT </li>

     *   <li> EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE = AT_CMD_TYPE_SET </li>

     *   <li> EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS = foo, 3 <li>

     * </ul>

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission

     * to receive.

     */

    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)

    public static final String ACTION_VENDOR_SPECIFIC_HEADSET_EVENT =
@@ -184,7 +192,7 @@ public final class BluetoothHeadset implements BluetoothProfile { 
            "android.bluetooth.headset.intent.category.companyid";



    /**

     * Headset state when SCO audio is not connected

     * Headset state when SCO audio is not connected.

     * This state can be one of

     * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} of

     * {@link #ACTION_AUDIO_STATE_CHANGED} intent.
@@ -192,7 +200,7 @@ public final class BluetoothHeadset implements BluetoothProfile { 
    public static final int STATE_AUDIO_DISCONNECTED = 10;



    /**

     * Headset state when SCO audio is connecting

     * Headset state when SCO audio is connecting.

     * This state can be one of

     * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} of

     * {@link #ACTION_AUDIO_STATE_CHANGED} intent.
@@ -200,7 +208,7 @@ public final class BluetoothHeadset implements BluetoothProfile { 
    public static final int STATE_AUDIO_CONNECTING = 11;



    /**

     * Headset state when SCO audio is connected

     * Headset state when SCO audio is connected.

     * This state can be one of

     * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} of

     * {@link #ACTION_AUDIO_STATE_CHANGED} intent.
@@ -410,7 +418,7 @@ public final class BluetoothHeadset implements BluetoothProfile { 
     * Stop Bluetooth Voice Recognition mode, and shut down the

     * Bluetooth audio path.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.

     *

     * @param device Bluetooth headset

     * @return false if there is no headset connected
@@ -433,7 +441,7 @@ public final class BluetoothHeadset implements BluetoothProfile { 
    /**

     * Check if Bluetooth SCO audio is connected.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.

     *

     * @param device Bluetooth headset

     * @return true if SCO is connected,

core/java/android/bluetooth/BluetoothProfile.java

+10 −7
Original line number Diff line number Diff line
@@ -105,6 +105,7 @@ public interface BluetoothProfile { 
     * from this intent.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}

     * permission.

     *

     * @param device Remote Bluetooth Device

     * @return false on immediate error,
@@ -132,6 +133,7 @@ public interface BluetoothProfile { 
     * two scenarios.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}

     * permission.

     *

     * @param device Remote Bluetooth Device

     * @return false on immediate error,
@@ -145,20 +147,20 @@ public interface BluetoothProfile { 
     *

     * <p> Return the set of devices which are in state {@link #STATE_CONNECTED}

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.

     *

     * @return List of devices. The list will be empty on error.

     */

    public List<BluetoothDevice> getConnectedDevices();



    /**

     * Get a set of devices that match any of the given connection

     * Get a list of devices that match any of the given connection

     * states.

     *

     * <p> If none of devices match any of the given states,

     * an empty set will be returned.

     * <p> If none of the devices match any of the given states,

     * an empty list will be returned.

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.

     *

     * @param states Array of states. States can be one of

     *              {@link #STATE_CONNECTED}, {@link #STATE_CONNECTING},
@@ -170,7 +172,7 @@ public interface BluetoothProfile { 
    /**

     * Get the current connection state of the profile

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.

     *

     * @param device Remote bluetooth device.

     * @return State of the profile connection. One of
@@ -187,6 +189,7 @@ public interface BluetoothProfile { 
     * {@link #PRIORITY_OFF},

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}

     * permission.

     *

     * @param device Paired bluetooth device

     * @param priority
@@ -202,7 +205,7 @@ public interface BluetoothProfile { 
     * {@link #PRIORITY_AUTO_CONNECT}, {@link #PRIORITY_OFF},

     * {@link #PRIORITY_ON}, {@link #PRIORITY_UNDEFINED}

     *

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}

     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.

     *

     * @param device Bluetooth device

     * @return priority of the device