Javadoc, and unhide the first pieces of the Bluetooth API.
With this commit there is enough public API to connect and use an RFCOMM
connection between Bluetooth devices.
</field>
</class>
</package>
+<package name="android.bluetooth"
+>
+<class name="BluetoothAdapter"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<method name="getRemoteDevice"
+ return="android.bluetooth.BluetoothDevice"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="address" type="java.lang.String">
+</parameter>
+</method>
+<method name="listenUsingRfcommOn"
+ return="android.bluetooth.BluetoothServerSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="channel" type="int">
+</parameter>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+</class>
+<class name="BluetoothDevice"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<implements name="android.os.Parcelable">
+</implements>
+<method name="createRfcommSocket"
+ return="android.bluetooth.BluetoothSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="channel" type="int">
+</parameter>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="describeContents"
+ return="int"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+<method name="getAddress"
+ return="java.lang.String"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+<method name="writeToParcel"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="out" type="android.os.Parcel">
+</parameter>
+<parameter name="flags" type="int">
+</parameter>
+</method>
+</class>
+<class name="BluetoothServerSocket"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<implements name="java.io.Closeable">
+</implements>
+<method name="accept"
+ return="android.bluetooth.BluetoothSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="accept"
+ return="android.bluetooth.BluetoothSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="timeout" type="int">
+</parameter>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="close"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+</class>
+<class name="BluetoothSocket"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<implements name="java.io.Closeable">
+</implements>
+<method name="close"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="connect"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="getInputStream"
+ return="java.io.InputStream"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="getOutputStream"
+ return="java.io.OutputStream"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="getRemoteDevice"
+ return="android.bluetooth.BluetoothDevice"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+</class>
+</package>
<package name="android.content"
>
<class name="AbstractCursorEntityIterator"
visibility="public"
>
</field>
+<field name="BLUETOOTH_SERVICE"
+ type="java.lang.String"
+ transient="false"
+ volatile="false"
+ value=""bluetooth""
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
<field name="CLIPBOARD_SERVICE"
type="java.lang.String"
transient="false"
/**
* Represents the local Bluetooth adapter.
*
- * @hide
+ * <p>Use {@link android.content.Context#getSystemService} with {@link
+ * android.content.Context#BLUETOOTH_SERVICE} to get the default local
+ * Bluetooth adapter. On most Android devices there is only one local
+ * Bluetotoh adapter.
+ *
+ * <p>Use the {@link BluetoothDevice} class for operations on remote Bluetooth
+ * devices.
+ *
+ * <p>TODO: unhide more of this class
*/
public final class BluetoothAdapter {
private static final String TAG = "BluetoothAdapter";
+ /** @hide */
public static final int BLUETOOTH_STATE_OFF = 0;
+ /** @hide */
public static final int BLUETOOTH_STATE_TURNING_ON = 1;
+ /** @hide */
public static final int BLUETOOTH_STATE_ON = 2;
+ /** @hide */
public static final int BLUETOOTH_STATE_TURNING_OFF = 3;
/** Inquiry scan and page scan are both off.
- * Device is neither discoverable nor connectable */
+ * Device is neither discoverable nor connectable
+ * @hide */
public static final int SCAN_MODE_NONE = 0;
/** Page scan is on, inquiry scan is off.
- * Device is connectable, but not discoverable */
+ * Device is connectable, but not discoverable
+ * @hide*/
public static final int SCAN_MODE_CONNECTABLE = 1;
/** Page scan and inquiry scan are on.
- * Device is connectable and discoverable */
+ * Device is connectable and discoverable
+ * @hide*/
public static final int SCAN_MODE_CONNECTABLE_DISCOVERABLE = 3;
+ /** @hide */
public static final int RESULT_FAILURE = -1;
+ /** @hide */
public static final int RESULT_SUCCESS = 0;
- /* The user will be prompted to enter a pin */
+ /** The user will be prompted to enter a pin
+ * @hide */
public static final int PAIRING_VARIANT_PIN = 0;
- /* The user will be prompted to enter a passkey */
+ /** The user will be prompted to enter a passkey
+ * @hide */
public static final int PAIRING_VARIANT_PASSKEY = 1;
- /* The user will be prompted to confirm the passkey displayed on the screen */
+ /** The user will be prompted to confirm the passkey displayed on the screen
+ * @hide */
public static final int PAIRING_VARIANT_CONFIRMATION = 2;
private final IBluetooth mService;
}
/**
- * Get the remote BluetoothDevice associated with the given MAC address.
- * Bluetooth MAC address must be upper case, such as "00:11:22:33:AA:BB".
+ * Get a {@link BluetoothDevice} object for the given Bluetooth hardware
+ * address.
+ * <p>Valid Bluetooth hardware addresses must be upper case, in a format
+ * such as "00:11:22:33:AA:BB".
+ * <p>A {@link BluetoothDevice} will always be returned for a valid
+ * hardware address, even if this adapter has never seen that device.
* @param address valid Bluetooth MAC address
+ * @throws IllegalArgumentException if address is invalid
*/
public BluetoothDevice getRemoteDevice(String address) {
return new BluetoothDevice(address);
* Is Bluetooth currently turned on.
*
* @return true if Bluetooth enabled, false otherwise.
+ * @hide
*/
public boolean isEnabled() {
try {
* Get the current state of Bluetooth.
*
* @return One of BLUETOOTH_STATE_ or BluetoothError.ERROR.
+ * @hide
*/
public int getBluetoothState() {
try {
* @return false if we cannot enable the Bluetooth device. True does not
* imply the device was enabled, it only implies that so far there were no
* problems.
+ * @hide
*/
public boolean enable() {
try {
* This turns off the underlying hardware.
*
* @return true if successful, false otherwise.
+ * @hide
*/
public boolean disable() {
try {
return false;
}
+ /** @hide */
public String getAddress() {
try {
return mService.getAddress();
* possible to retrieve the Bluetooth name when Bluetooth is enabled.
*
* @return the Bluetooth name, or null if there was a problem.
+ * @hide
*/
public String getName() {
try {
*
* @param name the name to set
* @return true, if the name was successfully set. False otherwise.
+ * @hide
*/
public boolean setName(String name) {
try {
* Get the current scan mode.
* Used to determine if the local device is connectable and/or discoverable
* @return Scan mode, one of SCAN_MODE_* or an error code
+ * @hide
*/
public int getScanMode() {
try {
* Set the current scan mode.
* Used to make the local device connectable and/or discoverable
* @param scanMode One of SCAN_MODE_*
+ * @hide
*/
public void setScanMode(int scanMode) {
try {
} catch (RemoteException e) {Log.e(TAG, "", e);}
}
+ /** @hide */
public int getDiscoverableTimeout() {
try {
return mService.getDiscoverableTimeout();
return -1;
}
+ /** @hide */
public void setDiscoverableTimeout(int timeout) {
try {
mService.setDiscoverableTimeout(timeout);
} catch (RemoteException e) {Log.e(TAG, "", e);}
}
+ /** @hide */
public boolean startDiscovery() {
try {
return mService.startDiscovery();
return false;
}
+ /** @hide */
public void cancelDiscovery() {
try {
mService.cancelDiscovery();
} catch (RemoteException e) {Log.e(TAG, "", e);}
}
+ /** @hide */
public boolean isDiscovering() {
try {
return mService.isDiscovering();
* returned.
*
* @return unmodifiable set of bonded devices, or null on error
+ * @hide
*/
public Set<BluetoothDevice> getBondedDevices() {
try {
}
/**
- * Construct a listening, secure RFCOMM server socket.
- * The remote device connecting to this socket will be authenticated and
+ * Create a listening, secure RFCOMM Bluetooth socket.
+ * <p>A remote device connecting to this socket will be authenticated and
* communication on this socket will be encrypted.
- * Call #accept to retrieve connections to this socket.
- * @return An RFCOMM BluetoothServerSocket
- * @throws IOException On error, for example Bluetooth not available, or
- * insufficient permissions.
+ * <p>Use {@link BluetoothServerSocket#accept} to retrieve incoming
+ * connections to listening {@link BluetoothServerSocket}.
+ * <p>Valid RFCOMM channels are in range 1 to 30.
+ * @param channel RFCOMM channel to listen on
+ * @return a listening RFCOMM BluetoothServerSocket
+ * @throws IOException on error, for example Bluetooth not available, or
+ * insufficient permissions, or channel in use.
*/
- public BluetoothServerSocket listenUsingRfcommOn(int port) throws IOException {
+ public BluetoothServerSocket listenUsingRfcommOn(int channel) throws IOException {
BluetoothServerSocket socket = new BluetoothServerSocket(
- BluetoothSocket.TYPE_RFCOMM, true, true, port);
+ BluetoothSocket.TYPE_RFCOMM, true, true, channel);
try {
socket.mSocket.bindListenNative();
} catch (IOException e) {
* @return An RFCOMM BluetoothServerSocket
* @throws IOException On error, for example Bluetooth not available, or
* insufficient permissions.
+ * @hide
*/
public BluetoothServerSocket listenUsingInsecureRfcommOn(int port) throws IOException {
BluetoothServerSocket socket = new BluetoothServerSocket(
* @return A SCO BluetoothServerSocket
* @throws IOException On error, for example Bluetooth not available, or
* insufficient permissions.
+ * @hide
*/
public static BluetoothServerSocket listenUsingScoOn() throws IOException {
BluetoothServerSocket socket = new BluetoothServerSocket(
/**
* Represents a remote Bluetooth device.
*
- * TODO: unhide
- * @hide
+ * <p>Use {@link BluetoothAdapter#getRemoteDevice} to create a {@link
+ * BluetoothDevice}.
+ *
+ * <p>This class is really just a thin wrapper for a Bluetooth hardware
+ * address. Objects of this class are immutable. Operations on this class
+ * are performed on the remote Bluetooth hardware address, using the
+ * {@link BluetoothAdapter} that was used to create this {@link
+ * BluetoothDevice}.
+ *
+ * TODO: unhide more of this class
*/
public final class BluetoothDevice implements Parcelable {
private static final String TAG = "BluetoothDevice";
/** We do not have a link key for the remote device, and are therefore not
- * bonded */
+ * bonded
+ * @hide*/
public static final int BOND_NOT_BONDED = 0;
- /** We have a link key for the remote device, and are probably bonded. */
+ /** We have a link key for the remote device, and are probably bonded.
+ * @hide */
public static final int BOND_BONDED = 1;
- /** We are currently attempting bonding */
+ /** We are currently attempting bonding
+ * @hide */
public static final int BOND_BONDING = 2;
//TODO: Unify these result codes in BluetoothResult or BluetoothError
/** A bond attempt failed because pins did not match, or remote device did
- * not respond to pin request in time */
+ * not respond to pin request in time
+ * @hide */
public static final int UNBOND_REASON_AUTH_FAILED = 1;
/** A bond attempt failed because the other side explicilty rejected
- * bonding */
+ * bonding
+ * @hide */
public static final int UNBOND_REASON_AUTH_REJECTED = 2;
- /** A bond attempt failed because we canceled the bonding process */
+ /** A bond attempt failed because we canceled the bonding process
+ * @hide */
public static final int UNBOND_REASON_AUTH_CANCELED = 3;
- /** A bond attempt failed because we could not contact the remote device */
+ /** A bond attempt failed because we could not contact the remote device
+ * @hide */
public static final int UNBOND_REASON_REMOTE_DEVICE_DOWN = 4;
- /** A bond attempt failed because a discovery is in progress */
+ /** A bond attempt failed because a discovery is in progress
+ * @hide */
public static final int UNBOND_REASON_DISCOVERY_IN_PROGRESS = 5;
- /** An existing bond was explicitly revoked */
+ /** An existing bond was explicitly revoked
+ * @hide */
public static final int UNBOND_REASON_REMOVED = 6;
- /* The user will be prompted to enter a pin */
+ //TODO: Remove duplicates between here and BluetoothAdapter
+ /** The user will be prompted to enter a pin
+ * @hide */
public static final int PAIRING_VARIANT_PIN = 0;
- /* The user will be prompted to enter a passkey */
+ /** The user will be prompted to enter a passkey
+ * @hide */
public static final int PAIRING_VARIANT_PASSKEY = 1;
- /* The user will be prompted to confirm the passkey displayed on the screen */
+ /** The user will be prompted to confirm the passkey displayed on the screen
+ * @hide */
public static final int PAIRING_VARIANT_CONFIRMATION = 2;
private static final int ADDRESS_LENGTH = 17;
return mAddress.hashCode();
}
+ /**
+ * Returns a string representation of this BluetoothDevice.
+ * <p>Currently this is the Bluetooth hardware address, for example
+ * "00:11:22:AA:BB:CC". However, you should always use {@link #getAddress}
+ * if you explicitly require the Bluetooth hardware address in case the
+ * {@link #toString} representation changes in the future.
+ * @return string representation of this BluetoothDevice
+ */
@Override
public String toString() {
return mAddress;
}
+ /** @hide */
public int describeContents() {
return 0;
}
+ /** @hide */
public static final Parcelable.Creator<BluetoothDevice> CREATOR =
new Parcelable.Creator<BluetoothDevice>() {
public BluetoothDevice createFromParcel(Parcel in) {
}
};
+ /** @hide */
public void writeToParcel(Parcel out, int flags) {
out.writeString(mAddress);
}
+ /**
+ * Returns the hardware address of this BluetoothDevice.
+ * <p> For example, "00:11:22:AA:BB:CC".
+ * @return Bluetooth hardware address as string
+ */
public String getAddress() {
return mAddress;
}
/**
- * Get the friendly Bluetooth name of this remote device.
+ * Get the friendly Bluetooth name of the remote device.
*
- * This name is visible to remote Bluetooth devices. Currently it is only
- * possible to retrieve the Bluetooth name when Bluetooth is enabled.
+ * <p>The local adapter will automatically retrieve remote names when
+ * performing a device scan, and will cache them. This method just returns
+ * the name for this device from the cache.
*
* @return the Bluetooth name, or null if there was a problem.
+ * @hide
*/
public String getName() {
try {
* @param address the remote device Bluetooth address.
* @return false If there was an immediate problem creating the bonding,
* true otherwise.
+ * @hide
*/
public boolean createBond() {
try {
/**
* Cancel an in-progress bonding request started with createBond.
+ * @hide
*/
public boolean cancelBondProcess() {
try {
*
* @return true if the device was disconnected, false otherwise and on
* error.
+ * @hide
*/
public boolean removeBond() {
try {
*
* @param address Bluetooth hardware address of the remote device to check.
* @return Result code
+ * @hide
*/
public int getBondState() {
try {
return BluetoothError.ERROR_IPC;
}
+ /** @hide */
public int getBluetoothClass() {
try {
return sService.getRemoteClass(mAddress);
return BluetoothError.ERROR_IPC;
}
+ /** @hide */
public String[] getUuids() {
try {
return sService.getRemoteUuids(mAddress);
return null;
}
+ /** @hide */
public int getServiceChannel(String uuid) {
try {
return sService.getRemoteServiceChannel(mAddress, uuid);
return BluetoothError.ERROR_IPC;
}
+ /** @hide */
public boolean setPin(byte[] pin) {
try {
return sService.setPin(mAddress, pin);
return false;
}
+ /** @hide */
public boolean setPasskey(int passkey) {
try {
return sService.setPasskey(mAddress, passkey);
return false;
}
+ /** @hide */
public boolean setPairingConfirmation(boolean confirm) {
try {
return sService.setPairingConfirmation(mAddress, confirm);
return false;
}
+ /** @hide */
public boolean cancelPairingUserInput() {
try {
return sService.cancelPairingUserInput(mAddress);
}
/**
- * Construct a secure RFCOMM socket ready to start an outgoing connection.
- * Call #connect on the returned #BluetoothSocket to begin the connection.
- * The remote device will be authenticated and communication on this socket
- * will be encrypted.
- * @param port remote port
- * @return an RFCOMM BluetoothSocket
+ * Create an RFCOMM {@link BluetoothSocket} ready to start a secure
+ * outgoing connection to this remote device.
+ * <p>The remote device will be authenticated and communication on this
+ * socket will be encrypted.
+ * <p>Use {@link BluetoothSocket#connect} to intiate the outgoing
+ * connection.
+ * <p>Valid RFCOMM channels are in range 1 to 30.
+ * @param channel RFCOMM channel to connect to
+ * @return a RFCOMM BluetoothServerSocket ready for an outgoing connection
* @throws IOException on error, for example Bluetooth not available, or
- * insufficient permissions.
+ * insufficient permissions
*/
- public BluetoothSocket createRfcommSocket(int port) throws IOException {
- return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, true, true, this, port);
+ public BluetoothSocket createRfcommSocket(int channel) throws IOException {
+ return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, true, true, this, channel);
}
/**
* @return An RFCOMM BluetoothSocket
* @throws IOException On error, for example Bluetooth not available, or
* insufficient permissions.
+ * @hide
*/
public BluetoothSocket createInsecureRfcommSocket(int port) throws IOException {
return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, false, false, this, port);
* @return a SCO BluetoothSocket
* @throws IOException on error, for example Bluetooth not available, or
* insufficient permissions.
+ * @hide
*/
public BluetoothSocket createScoSocket() throws IOException {
return new BluetoothSocket(BluetoothSocket.TYPE_SCO, -1, true, true, this, -1);
* @param pin pin as java String
* @return the pin code as a UTF8 byte array, or null if it is an invalid
* Bluetooth pin.
+ * @hide
*/
public static byte[] convertPinToBytes(String pin) {
if (pin == null) {
return pinBytes;
}
- /** Sanity check a bluetooth address, such as "00:43:A8:23:10:F0" */
+ /** Sanity check a bluetooth address, such as "00:43:A8:23:10:F0"
+ * @hide */
public static boolean checkBluetoothAddress(String address) {
if (address == null || address.length() != ADDRESS_LENGTH) {
return false;
import java.io.IOException;
/**
- * Server (listening) Bluetooth Socket.
+ * A listening Bluetooth socket.
*
- * Currently only supports RFCOMM sockets.
+ * <p>The interface for Bluetooth Sockets is similar to that of TCP sockets:
+ * {@link java.net.Socket} and {@link java.net.ServerSocket}. On the server
+ * side, use a {@link BluetoothServerSocket} to create a listening server
+ * socket. It will return a new, connected {@link BluetoothSocket} on an
+ * accepted connection. On the client side, use the same
+ * {@link BluetoothSocket} object to both intiate the outgoing connection,
+ * and to manage the connected socket.
*
- * RFCOMM is a connection orientated, streaming transport over Bluetooth. It is
- * also known as the Serial Port Profile (SPP).
+ * <p>The most common type of Bluetooth Socket is RFCOMM. RFCOMM is a
+ * connection orientated, streaming transport over Bluetooth. It is also known
+ * as the Serial Port Profile (SPP).
*
- * TODO: Consider exposing L2CAP sockets.
- * TODO: Clean up javadoc grammer and formatting.
- * TODO: Remove @hide
- * @hide
+ * <p>Use {@link BluetoothDevice#createRfcommSocket} to create a new {@link
+ * BluetoothSocket} ready for an outgoing connection to a remote
+ * {@link BluetoothDevice}.
+ *
+ * <p>Use {@link BluetoothAdapter#listenUsingRfcommOn} to create a listening
+ * {@link BluetoothServerSocket} ready for incoming connections to the local
+ * {@link BluetoothAdapter}.
+ *
+ * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread
+ * safe. In particular, {@link #close} will always immediately abort ongoing
+ * operations and close the socket.
*/
public final class BluetoothServerSocket implements Closeable {
/*package*/ final BluetoothSocket mSocket;
/**
* Block until a connection is established.
- * Returns a connected #BluetoothSocket. This server socket can be reused
- * for subsequent incoming connections by calling #accept repeatedly.
- * #close can be used to abort this call from another thread.
- * @return A connected #BluetoothSocket
- * @throws IOException On error, for example this call was aborted
+ * <p>Returns a connected {@link BluetoothSocket} on successful connection.
+ * <p>Once this call returns, it can be called again to accept subsequent
+ * incoming connections.
+ * <p>{@link #close} can be used to abort this call from another thread.
+ * @return a connected {@link BluetoothSocket}
+ * @throws IOException on error, for example this call was aborted, or
+ * timeout
*/
public BluetoothSocket accept() throws IOException {
return accept(-1);
/**
* Block until a connection is established, with timeout.
- * Returns a connected #BluetoothSocket. This server socket can be reused
- * for subsequent incoming connections by calling #accept repeatedly.
- * #close can be used to abort this call from another thread.
- * @return A connected #BluetoothSocket
- * @throws IOException On error, for example this call was aborted, or
+ * <p>Returns a connected {@link BluetoothSocket} on successful connection.
+ * <p>Once this call returns, it can be called again to accept subsequent
+ * incoming connections.
+ * <p>{@link #close} can be used to abort this call from another thread.
+ * @return a connected {@link BluetoothSocket}
+ * @throws IOException on error, for example this call was aborted, or
* timeout
*/
public BluetoothSocket accept(int timeout) throws IOException {
}
/**
- * Closes this socket.
- * This will cause other blocking calls on this socket to immediately
+ * Immediately close this socket, and release all associated resources.
+ * <p>Causes blocked calls on this socket in other threads to immediately
* throw an IOException.
*/
public void close() throws IOException {
import java.io.OutputStream;
/**
- * Represents a connected or connecting Bluetooth Socket.
+ * A connected or connecting Bluetooth socket.
*
- * Currently only supports RFCOMM sockets.
+ * <p>The interface for Bluetooth Sockets is similar to that of TCP sockets:
+ * {@link java.net.Socket} and {@link java.net.ServerSocket}. On the server
+ * side, use a {@link BluetoothServerSocket} to create a listening server
+ * socket. It will return a new, connected {@link BluetoothSocket} on an
+ * accepted connection. On the client side, use the same
+ * {@link BluetoothSocket} object to both intiate the outgoing connection,
+ * and to manage the connected socket.
*
- * RFCOMM is a connection orientated, streaming transport over Bluetooth. It is
- * also known as the Serial Port Profile (SPP).
+ * <p>The most common type of Bluetooth Socket is RFCOMM. RFCOMM is a
+ * connection orientated, streaming transport over Bluetooth. It is also known
+ * as the Serial Port Profile (SPP).
*
- * TODO: Consider exposing L2CAP sockets.
- * TODO: Clean up javadoc grammer and formatting.
- * TODO: Remove @hide
- * @hide
+ * <p>Use {@link BluetoothDevice#createRfcommSocket} to create a new {@link
+ * BluetoothSocket} ready for an outgoing connection to a remote
+ * {@link BluetoothDevice}.
+ *
+ * <p>Use {@link BluetoothAdapter#listenUsingRfcommOn} to create a listening
+ * {@link BluetoothServerSocket} ready for incoming connections to the local
+ * {@link BluetoothAdapter}.
+ *
+ * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread
+ * safe. In particular, {@link #close} will always immediately abort ongoing
+ * operations and close the socket.
*/
public final class BluetoothSocket implements Closeable {
- /** Keep TYPE_RFCOMM etc in sync with BluetoothSocket.cpp */
+ /** Keep TYPE_ fields in sync with BluetoothSocket.cpp */
/*package*/ static final int TYPE_RFCOMM = 1;
/*package*/ static final int TYPE_SCO = 2;
/*package*/ static final int TYPE_L2CAP = 3;
this(type, fd, auth, encrypt, new BluetoothDevice(address), port);
}
+ /** @hide */
@Override
protected void finalize() throws Throwable {
try {
/**
* Attempt to connect to a remote device.
- * This method will block until a connection is made or the connection
+ * <p>This method will block until a connection is made or the connection
* fails. If this method returns without an exception then this socket
- * is now connected. #close can be used to abort this call from another
- * thread.
- * @throws IOException On error, for example connection failure
+ * is now connected.
+ * <p>{@link #close} can be used to abort this call from another thread.
+ * @throws IOException on error, for example connection failure
*/
public void connect() throws IOException {
connectNative();
}
/**
- * Closes this socket.
- * This will cause other blocking calls on this socket to immediately
+ * Immediately close this socket, and release all associated resources.
+ * <p>Causes blocked calls on this socket in other threads to immediately
* throw an IOException.
*/
public void close() throws IOException {
}
/**
- * Return the remote device we are connecting, or connected, to.
- * @return remote device, or null if this socket has not yet attempted
- * or established a connection.
+ * Get the remote device this socket is connecting, or connected, to.
+ * @return remote device
*/
public BluetoothDevice getRemoteDevice() {
return mDevice;
/**
* Get the input stream associated with this socket.
- * The input stream will be returned even if the socket is not yet
+ * <p>The input stream will be returned even if the socket is not yet
* connected, but operations on that stream will throw IOException until
* the associated socket is connected.
* @return InputStream
/**
* Get the output stream associated with this socket.
- * The output stream will be returned even if the socket is not yet
+ * <p>The output stream will be returned even if the socket is not yet
* connected, but operations on that stream will throw IOException until
* the associated socket is connected.
* @return OutputStream
*
* @see #getSystemService
* @see android.bluetooth.BluetoothAdapter
- * @hide
*/
public static final String BLUETOOTH_SERVICE = "bluetooth";
/**
OSDN Git Service
