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

Commit 8ef1179e authored by Jaikumar Ganesh's avatar Jaikumar Ganesh Committed by Android (Google) Code Review
Browse files

Merge "Improve readability of java docs for the public APIs." into honeycomb

parents 1e0bad61 c8fa4ff8

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