BluetoothSocket

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.

Summary

Constants

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

Constants

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 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
BluetoothSocketException in case of failure, with the corresponding error code.
IOException for other errors (eg: InputStream read failures etc.).

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.

Returns
String a string representation of the object.