Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Jaikumar Ganesh
2011-01-26 09:02:12 -08:00
committed by Android (Google) Code Review
parent 1e0bad6156 c8fa4ff838
commit 8ef1179efc
4 changed files with 83 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
core/java/android/bluetooth/BluetoothA2dp.java
View File

@@ -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,

18
core/java/android/bluetooth/BluetoothDevice.java
View File

@@ -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

68
core/java/android/bluetooth/BluetoothHeadset.java
View File

@@ -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,

17
core/java/android/bluetooth/BluetoothProfile.java
View File

@@ -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