Package ej.bluetooth

## Class BluetoothConnection

- java.lang.Object
- - ej.bluetooth.BluetoothConnection

-     public class BluetoothConnection
      extends Object

  The `BluetoothConnection` class represents a connection with a remote Bluetooth device.

  Connections may be retrieved by listening to `connection events` while `connecting` to a device or while `advertising`. The GAP events related to a device may be handled by `setting the connection listener` of the adapter.

  This class provides a method to get the address of the remote device. It also allows to disconnect to the device, to manage pairing and to discover the services that the device provides.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BluetoothConnection()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `disconnect()` | Initiates a disconnection from the device.
    `boolean` | `discoverService​(BluetoothUuid uuid)` | Discovers the service with the given UUID provided by the device.
    `boolean` | `discoverServices()` | Discovers all the services provided by the device.
    `BluetoothAddress` | `getAddress()` | Returns the Bluetooth address of the device.
    `boolean` | `sendExecuteWriteResponse​(BluetoothAttribute attribute, byte status)` | Sends the response to an execute write request sent by a device on the given attribute.
    `boolean` | `sendNotification​(BluetoothCharacteristic characteristic, byte[] value, boolean confirm)` | Sends a notification or indication on the given characteristic to a device.
    `boolean` | `sendPairRequest()` | Initiates pairing with the device.
    `boolean` | `sendPairResponse​(boolean accept)` | Replies to the pairing request of the device.
    `boolean` | `sendPasskeyResponse​(boolean accept, int passkey)` | Replies to the passkey request of the device.
    `boolean` | `sendPrepareWriteResponse​(BluetoothAttribute attribute, byte status, byte[] value, int offset)` | Sends the response to a prepare write request sent by a device on the given attribute.
    `boolean` | `sendReadRequest​(BluetoothAttribute attribute)` | Sends a read request on the given attribute.
    `boolean` | `sendReadResponse​(BluetoothAttribute attribute, byte status, byte[] value)` | Sends the response to a read request sent by a device on the given attribute.
    `boolean` | `sendWriteRequest​(BluetoothAttribute attribute, byte[] value)` | Sends a write request on the given attribute.
    `boolean` | `sendWriteResponse​(BluetoothAttribute attribute, byte status)` | Sends the response to a write request sent by a device on the given attribute.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### BluetoothConnection

          public BluetoothConnection()

  - ### Method Detail

    - #### getAddress

          public BluetoothAddress getAddress()

      Returns the Bluetooth address of the device.
      Returns:
        the Bluetooth address of the device.

    - #### disconnect

          public boolean disconnect()

      Initiates a disconnection from the device.
      Returns:
        true if disconnection was initiated successfully, false otherwise.
      See Also:
        `ConnectionListener.onDisconnected(BluetoothConnection)`

    - #### sendPairRequest

          public boolean sendPairRequest()

      Initiates pairing with the device.

      This operation may only be performed while the adapter is still connected to the device.

      Returns:
        true if pairing was initiated successfully, false otherwise.
      See Also:
        `ConnectionListener.onPairCompleted(BluetoothConnection, boolean)`, `ConnectionListener.onPasskeyRequest(BluetoothConnection)`

    - #### sendPairResponse

          public boolean sendPairResponse​(boolean accept)

      Replies to the pairing request of the device.

      This operation may only be performed after receiving a pairing request.

      Parameters:
        `accept` - true if the pairing request should be accepted, false otherwise.
      Returns:
        true if the reply was sent successfully, false otherwise.
      See Also:
        `ConnectionListener.onPairCompleted(BluetoothConnection, boolean)`, `ConnectionListener.onPasskeyGenerated(BluetoothConnection, int)`

    - #### sendPasskeyResponse

          public boolean sendPasskeyResponse​(boolean accept,
                                             int passkey)

      Replies to the passkey request of the device.

      This operation may only be performed after receiving a passkey request.

      Parameters:
        `accept` - true if the passkey request should be accepted, false otherwise.
        `passkey` - the passkey value (6-digits PIN code). This parameter is used only if the request is accepted.
      Returns:
        true if the reply was sent successfully, false otherwise.
      See Also:
        `ConnectionListener.onPairCompleted(BluetoothConnection, boolean)`

    - #### discoverServices

          public boolean discoverServices()

      Discovers all the services provided by the device.

      This operation may only be performed while the adapter is still connected to the device. In order to discover specific services only, use `discoverService(BluetoothUuid)` instead.

      Returns:
        true if service discovery was initiated successfully, false otherwise.
      See Also:
        `discoverService(BluetoothUuid)`, `ConnectionListener.onDiscoveryResult(BluetoothConnection, BluetoothService)`, `ConnectionListener.onDiscoveryCompleted(BluetoothConnection)`

    - #### discoverService

          public boolean discoverService​(BluetoothUuid uuid)

      Discovers the service with the given UUID provided by the device.

      This operation may only be performed while the adapter is still connected to the device. In order to discover all services, use `discoverServices()` instead.

      Parameters:
        `uuid` - the UUID of the service to discover.
      Returns:
        true if service discovery was initiated successfully, false otherwise.
      See Also:
        `discoverServices()`, `ConnectionListener.onDiscoveryResult(BluetoothConnection, BluetoothService)`, `ConnectionListener.onDiscoveryCompleted(BluetoothConnection)`

    - #### sendReadRequest

          public boolean sendReadRequest​(BluetoothAttribute attribute)

      Sends a read request on the given attribute.
      Parameters:
        `attribute` - the attribute to send a read request on.
      Returns:
        true if the read request was sent successfully.
      Throws:
        `IllegalArgumentException` - if the attribute is not a remote attribute.
        `IllegalArgumentException` - if the attribute does not belong to the device.
      See Also:
        `RemoteServiceListener.onReadCompleted(BluetoothConnection, BluetoothAttribute, byte, byte[])`

    - #### sendWriteRequest

          public boolean sendWriteRequest​(BluetoothAttribute attribute,
                                          byte[] value)

      Sends a write request on the given attribute.
      Parameters:
        `attribute` - the attribute to send a write request on.
        `value` - the value to write.
      Returns:
        true if the write request was sent successfully.
      Throws:
        `IllegalArgumentException` - if the attribute is not a remote attribute.
        `IllegalArgumentException` - if the attribute does not belong to the device.
      See Also:
        `RemoteServiceListener.onWriteCompleted(BluetoothConnection, BluetoothAttribute, byte)`

    - #### sendReadResponse

          public boolean sendReadResponse​(BluetoothAttribute attribute,
                                          byte status,
                                          byte[] value)

      Sends the response to a read request sent by a device on the given attribute.
      Parameters:
        `attribute` - the attribute on which the request was sent.
        `status` - the status to send back (see `BluetoothStatus`).
        `value` - the value to send back.
      Returns:
        true if the read response was sent successfully.
      Throws:
        `IllegalArgumentException` - if the attribute is not a local attribute.

    - #### sendWriteResponse

          public boolean sendWriteResponse​(BluetoothAttribute attribute,
                                           byte status)

      Sends the response to a write request sent by a device on the given attribute.
      Parameters:
        `attribute` - the attribute on which the request was sent.
        `status` - the status to send back (see `BluetoothStatus`).
      Returns:
        true if the write response was sent successfully.
      Throws:
        `IllegalArgumentException` - if the attribute is not a local attribute.

    - #### sendPrepareWriteResponse

          public boolean sendPrepareWriteResponse​(BluetoothAttribute attribute,
                                                  byte status,
                                                  byte[] value,
                                                  int offset)

      Sends the response to a prepare write request sent by a device on the given attribute.
      Parameters:
        `attribute` - the attribute on which the request was sent.
        `status` - the status to send back (see `BluetoothStatus`).
        `value` - the value of the prepare write request.
        `offset` - the offset of the prepare write request.
      Returns:
        true if the prepare write response was sent successfully.
      Throws:
        `IllegalArgumentException` - if the attribute is not a local attribute.

    - #### sendExecuteWriteResponse

          public boolean sendExecuteWriteResponse​(BluetoothAttribute attribute,
                                                  byte status)

      Sends the response to an execute write request sent by a device on the given attribute.
      Parameters:
        `attribute` - the attribute on which the request was sent.
        `status` - the status to send back (see `BluetoothStatus`).
      Returns:
        true if the execute write response was sent successfully.
      Throws:
        `IllegalArgumentException` - if the attribute is not a local attribute.

    - #### sendNotification

          public boolean sendNotification​(BluetoothCharacteristic characteristic,
                                          byte[] value,
                                          boolean confirm)

      Sends a notification or indication on the given characteristic to a device.
      Parameters:
        `characteristic` - the characteristic to send a notification on.
        `value` - the value to send.
        `confirm` - true to request a confirmation (GATT indication), false otherwise (GATT notification).
      Returns:
        true if the notification was sent successfully.
      Throws:
        `IllegalArgumentException` - if the characteristic is not a local characteristic.
      See Also:
        `LocalServiceListener.onNotificationSent(BluetoothConnection, BluetoothCharacteristic, boolean)`