Added in API level 5

Summary: Constants | Methods | Inherited Methods

BluetoothSocket

Kotlin |Java

public final class BluetoothSocket
extends Object implements Closeable

java.lang.Object
↳	android.bluetooth.BluetoothSocket

A connected or connecting Bluetooth socket.

The interface for Bluetooth Sockets is similar to that of TCP sockets: Socket and ServerSocket. On the server side, use a BluetoothServerSocket to create a listening server socket. When a connection is accepted by the BluetoothServerSocket, it will return a new BluetoothSocket to manage the connection. On the client side, use a single BluetoothSocket to both initiate an outgoing connection and to manage the connection.

The most common type of Bluetooth socket is RFCOMM, which is the type supported by the Android APIs. RFCOMM is a connection-oriented, streaming transport over Bluetooth. It is also known as the Serial Port Profile (SPP).

To create a BluetoothSocket for connecting to a known device, use BluetoothDevice.createRfcommSocketToServiceRecord(). Then call connect() to attempt a connection to the remote device. This call will block until a connection is established or the connection fails.

To create a BluetoothSocket as a server (or "host"), see the BluetoothServerSocket documentation.

Once the socket is connected, whether initiated as a client or accepted as a server, open the IO streams by calling getInputStream() and getOutputStream() in order to retrieve InputStream and OutputStream objects, respectively, which are automatically connected to the socket.

BluetoothSocket is thread safe. In particular, close() will always immediately abort ongoing operations and close the socket.

Developer Guides

For more information about using Bluetooth, read the Bluetooth developer guide.

See also:

Summary

Constants
`String`	`BLUETOOTH_OFF_FAILURE_MSG` IOException message for `connect()` when Bluetooth is off and socket connection is triggered.
`String`	`L2CAP_ACL_FAILURE_MSG` IOException message for `connect()` when there is an ACL connection failure.
`String`	`L2CAP_CLIENT_SECURITY_FAILURE_MSG` IOException message for `connect()` when security clearance fails on the client during L2CAP connection.
`String`	`L2CAP_INSUFFICIENT_AUTHENTICATION_MSG` IOException message for `connect()` when authentication fails on the peer device during L2CAP connection.
`String`	`L2CAP_INSUFFICIENT_AUTHORIZATION_MSG` IOException message for `connect()` when authorization fails on the peer device during L2CAP connection.
`String`	`L2CAP_INSUFFICIENT_ENCRYPTION_MSG` IOException message for `connect()` for insufficient encryption from the peer device during L2CAP connection.
`String`	`L2CAP_INSUFFICIENT_ENCRYPT_KEY_SIZE_MSG` IOException message for `connect()` indicating insufficient encryption key size on the peer device during L2CAP connection.
`String`	`L2CAP_INVALID_PARAMETERS_MSG` IOException message for `connect()` for invalid parameters from the peer device during L2CAP connection.
`String`	`L2CAP_INVALID_SOURCE_CID_MSG` IOException message for `connect()` for invalid Channel ID from the peer device during L2CAP connection.
`String`	`L2CAP_NO_PSM_AVAILABLE_MSG` IOException message for `connect()` when no PSM is available for L2CAP connection.
`String`	`L2CAP_NO_RESOURCES_MSG` IOException message for `connect()` when no resources are available for L2CAP connection.
`String`	`L2CAP_SOURCE_CID_ALREADY_ALLOCATED_MSG` IOException message for `connect()` for already allocated Channel ID from the peer device during L2CAP connection.
`String`	`L2CAP_TIMEOUT_MSG` IOException message for `connect()` when L2CAP connection timeout.
`String`	`L2CAP_UNACCEPTABLE_PARAMETERS_MSG` IOException message for `connect()` for unacceptable Parameters from the peer device during L2CAP connection.
`String`	`L2CAP_UNKNOWN_ERR_MSG` IOException message for `connect()` for unknown L2CAP error.
`String`	`NULL_DEVICE_ERR_MSG` IOException message for `connect()` when null device attempts to do socket connection.
`String`	`SOCKET_CLOSED_MSG` IOException message for `connect()` when socket is closed.
`String`	`SOCKET_CONNECTION_FAILURE_MSG` IOException message for `connect()` for generic socket connection failures.
`String`	`SOCKET_MANAGER_FAILURE_MSG` IOException message for `connect()` when socket manager is not available.
`int`	`TYPE_L2CAP` L2CAP socket
`int`	`TYPE_RFCOMM` RFCOMM socket
`int`	`TYPE_SCO` SCO socket

Public methods
`void`	`close()` Closes this stream and releases any system resources associated with it.
`void`	`connect()` Attempt to connect to a remote device.
`int`	`getConnectionType()` Get the type of the underlying connection.
`InputStream`	`getInputStream()` Get the input stream associated with this socket.
`int`	`getMaxReceivePacketSize()` Get the maximum supported Receive packet size for the underlying transport.
`int`	`getMaxTransmitPacketSize()` Get the maximum supported Transmit packet size for the underlying transport.
`OutputStream`	`getOutputStream()` Get the output stream associated with this socket.
`BluetoothDevice`	`getRemoteDevice()` Get the remote device this socket is connecting, or connected, to.
`boolean`	`isConnected()` Get the connection status of this socket, ie, whether there is an active connection with remote device.
`String`	`toString()` Returns a string representation of the object.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

From interface


        
          java.io.Closeable


      close()

Closes this stream and releases any system resources associated with it.

From interface


        
          java.lang.AutoCloseable


      close()

Closes this resource, relinquishing any underlying resources.

Constants

BLUETOOTH_OFF_FAILURE_MSG

Added in Android UpsideDownCake

public static final String BLUETOOTH_OFF_FAILURE_MSG

IOException message for connect() when Bluetooth is off and socket connection is triggered.

Constant Value: "Bluetooth is off"

L2CAP_ACL_FAILURE_MSG

Added in Android UpsideDownCake

public static final String L2CAP_ACL_FAILURE_MSG

IOException message for connect() when there is an ACL connection failure.

Constant Value: "ACL connection failed"

L2CAP_CLIENT_SECURITY_FAILURE_MSG

Added in Android UpsideDownCake

public static final String L2CAP_CLIENT_SECURITY_FAILURE_MSG

IOException message for connect() when security clearance fails on the client during L2CAP connection.

Constant Value: "Client security clearance failed"

L2CAP_INSUFFICIENT_AUTHENTICATION_MSG

Added in Android UpsideDownCake

public static final String L2CAP_INSUFFICIENT_AUTHENTICATION_MSG

IOException message for connect() when authentication fails on the peer device during L2CAP connection.

Constant Value: "Insufficient authentication"

L2CAP_INSUFFICIENT_AUTHORIZATION_MSG

Added in Android UpsideDownCake

public static final String L2CAP_INSUFFICIENT_AUTHORIZATION_MSG

IOException message for connect() when authorization fails on the peer device during L2CAP connection.

Constant Value: "Insufficient authorization"

L2CAP_INSUFFICIENT_ENCRYPTION_MSG

Added in Android UpsideDownCake

public static final String L2CAP_INSUFFICIENT_ENCRYPTION_MSG

IOException message for connect() for insufficient encryption from the peer device during L2CAP connection.

Constant Value: "Insufficient encryption"

L2CAP_INSUFFICIENT_ENCRYPT_KEY_SIZE_MSG

Added in Android UpsideDownCake

public static final String L2CAP_INSUFFICIENT_ENCRYPT_KEY_SIZE_MSG

IOException message for connect() indicating insufficient encryption key size on the peer device during L2CAP connection.

Constant Value: "Insufficient encryption key size"

L2CAP_INVALID_PARAMETERS_MSG

Added in Android UpsideDownCake

public static final String L2CAP_INVALID_PARAMETERS_MSG

IOException message for connect() for invalid parameters from the peer device during L2CAP connection.

Constant Value: "Invalid Parameters"

L2CAP_INVALID_SOURCE_CID_MSG

Added in Android UpsideDownCake

public static final String L2CAP_INVALID_SOURCE_CID_MSG

IOException message for connect() for invalid Channel ID from the peer device during L2CAP connection.

Constant Value: "Invalid source CID"

L2CAP_NO_PSM_AVAILABLE_MSG

Added in Android UpsideDownCake

public static final String L2CAP_NO_PSM_AVAILABLE_MSG

IOException message for connect() when no PSM is available for L2CAP connection.

Constant Value: "No PSM available"

L2CAP_NO_RESOURCES_MSG

Added in Android UpsideDownCake

public static final String L2CAP_NO_RESOURCES_MSG

IOException message for connect() when no resources are available for L2CAP connection.

Constant Value: "No resources Available"

L2CAP_SOURCE_CID_ALREADY_ALLOCATED_MSG

Added in Android UpsideDownCake

public static final String L2CAP_SOURCE_CID_ALREADY_ALLOCATED_MSG

IOException message for connect() for already allocated Channel ID from the peer device during L2CAP connection.

Constant Value: "Source CID already allocated"

L2CAP_TIMEOUT_MSG

Added in Android UpsideDownCake

public static final String L2CAP_TIMEOUT_MSG

IOException message for connect() when L2CAP connection timeout.

Constant Value: "Connection Timeout"

L2CAP_UNACCEPTABLE_PARAMETERS_MSG

Added in Android UpsideDownCake

public static final String L2CAP_UNACCEPTABLE_PARAMETERS_MSG

IOException message for connect() for unacceptable Parameters from the peer device during L2CAP connection.

Constant Value: "Unacceptable Parameters"

L2CAP_UNKNOWN_ERR_MSG

Added in Android UpsideDownCake

public static final String L2CAP_UNKNOWN_ERR_MSG

IOException message for connect() for unknown L2CAP error.

Constant Value: "Connection failed for unknown reason"

NULL_DEVICE_ERR_MSG

Added in Android UpsideDownCake

public static final String NULL_DEVICE_ERR_MSG

IOException message for connect() when null device attempts to do socket connection.

Constant Value: "Connect is called on null device"

SOCKET_CLOSED_MSG

Added in Android UpsideDownCake

public static final String SOCKET_CLOSED_MSG

IOException message for connect() when socket is closed.

Constant Value: "socket closed"

SOCKET_CONNECTION_FAILURE_MSG

Added in Android UpsideDownCake

public static final String SOCKET_CONNECTION_FAILURE_MSG

IOException message for connect() for generic socket connection failures.

Constant Value: "bt socket connect failed"

SOCKET_MANAGER_FAILURE_MSG

Added in Android UpsideDownCake

public static final String SOCKET_MANAGER_FAILURE_MSG

IOException message for connect() when socket manager is not available.

Constant Value: "bt get socket manager failed"

TYPE_L2CAP

Added in API level 23

public static final int TYPE_L2CAP

L2CAP socket

Constant Value: 3 (0x00000003)

TYPE_RFCOMM

Added in API level 23

public static final int TYPE_RFCOMM

RFCOMM socket

Constant Value: 1 (0x00000001)

TYPE_SCO

Added in API level 23

public static final int TYPE_SCO

SCO socket

Constant Value: 2 (0x00000002)

Public methods

close

Added in API level 5

public void close ()

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

As noted in AutoCloseable#close(), cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the Closeable as closed, prior to throwing the IOException.

Throws
`IOException`

connect

Added in API level 5

public void connect ()

Attempt to connect to a remote device.

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.

Creating new connections to remote Bluetooth devices should not be attempted while device discovery is in progress. Device discovery is a heavyweight procedure on the Bluetooth adapter and will significantly slow a device connection. Use BluetoothAdapter#cancelDiscovery() to cancel an ongoing discovery. Discovery is not managed by the Activity, but is run as a system service, so an application should always call BluetoothAdapter#cancelDiscovery() even if it did not directly request a discovery, just to be sure.

close() can be used to abort this call from another thread.

For failures, an IOException is thrown with a message as follows -

ERROR(/NULL_DEVICE_ERR_MSG): If device is null.

ERROR(/SOCKET_CLOSED_MSG) : If socket is already closed.

ERROR(/BLUETOOTH_OFF_FAILURE_MSG): If Bluetooth is turned off.

ERROR(/SOCKET_MANAGER_FAILURE_MSG): If couldn't get socket manager.

ERROR(/L2CAP_ACL_FAILURE_MSG): If ACL connection failure during L2CAP socket connection.

ERROR(/L2CAP_CLIENT_SECURITY_FAILURE_MSG): If L2CAP Client security clearance failure.

ERROR(/L2CAP_INSUFFICIENT_AUTHENTICATION_MSG): If Peer authentication failure during L2CAP connection.

ERROR(/L2CAP_INSUFFICIENT_AUTHORIZATION_MSG): If Peer authorization failure during L2CAP connection.

ERROR(/L2CAP_INSUFFICIENT_ENCRYPT_KEY_SIZE_MSG): If Insufficient encryption key size.

ERROR(/L2CAP_INSUFFICIENT_ENCRYPTION_MSG): If Insufficient encryption for L2CAP connection.

ERROR(/L2CAP_INVALID_SOURCE_CID_MSG): If Source CID is invalid.

ERROR(/L2CAP_SOURCE_CID_ALREADY_ALLOCATED_MSG): If Source CID is already allocated.

ERROR(/L2CAP_UNACCEPTABLE_PARAMETERS_MSG): If Unacceptable parameters for L2CAP socket.

ERROR(/L2CAP_INVALID_PARAMETERS_MSG): If Invalid parameters for L2CAP socket.

ERROR(/L2CAP_NO_RESOURCES_MSG): If No resources available for L2CAP connection.

ERROR(/L2CAP_NO_PSM_AVAILABLE_MSG): If No PSM available for L2CAP connection

ERROR(/L2CAP_TIMEOUT_MSG): If L2CAP connection timeout.

ERROR(/SOCKET_CONNECTION_FAILURE_MSG): If a generic socket connection excluding one above occurs.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Throws
`IOException`	on error.

getConnectionType

Added in API level 23

public int getConnectionType ()

Get the type of the underlying connection.

Returns
`int`	one of `TYPE_RFCOMM`, `TYPE_SCO` or `TYPE_L2CAP`

getInputStream

Added in API level 5

public InputStream getInputStream ()

Get the input stream associated with this socket.

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.

Returns
`InputStream`	InputStream

Throws
`IOException`

getMaxReceivePacketSize

Added in API level 23

public int getMaxReceivePacketSize ()

Get the maximum supported Receive packet size for the underlying transport. Use this to optimize the reads done on the input stream, as any call to read will return a maximum of this amount of bytes - or for some transports a multiple of this value.

Returns
`int`	the maximum supported Receive packet size for the underlying transport.

getMaxTransmitPacketSize

Added in API level 23

public int getMaxTransmitPacketSize ()

Get the maximum supported Transmit packet size for the underlying transport. Use this to optimize the writes done to the output socket, to avoid sending half full packets.

Returns
`int`	the maximum supported Transmit packet size for the underlying transport.

getOutputStream

Added in API level 5

public OutputStream getOutputStream ()

Get the output stream associated with this socket.

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.

Returns
`OutputStream`	OutputStream

Throws
`IOException`

getRemoteDevice

Added in API level 5

public BluetoothDevice getRemoteDevice ()

Get the remote device this socket is connecting, or connected, to.

Returns
`BluetoothDevice`	remote device

isConnected

Added in API level 14

public boolean isConnected ()

Get the connection status of this socket, ie, whether there is an active connection with remote device.

Returns
`boolean`	true if connected false if not connected

toString

Added in API level 5

public String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Returns
`String`	a string representation of the object.