hardware/bluetooth.h

   1 /*
   2  * Copyright (C) 2012 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_INCLUDE_BLUETOOTH_H
  18 #define ANDROID_INCLUDE_BLUETOOTH_H
  19
  20 #include <stdint.h>
  21 #include <sys/cdefs.h>
  22 #include <sys/types.h>
  23
  24 #include <hardware/hardware.h>
  25
  26 __BEGIN_DECLS
  27
  28 /**
  29  * The Bluetooth Hardware Module ID
  30  */
  31
  32 #define BT_HARDWARE_MODULE_ID "bluetooth"
  33 #define BT_STACK_MODULE_ID "bluetooth"
  34 #define BT_STACK_TEST_MODULE_ID "bluetooth_test"
  35
  36
  37 /* Bluetooth profile interface IDs */
  38
  39 #define BT_PROFILE_HANDSFREE_ID "handsfree"
  40 #define BT_PROFILE_ADVANCED_AUDIO_ID "a2dp"
  41 #define BT_PROFILE_HEALTH_ID "health"
  42 #define BT_PROFILE_SOCKETS_ID "socket"
  43 #define BT_PROFILE_HIDHOST_ID "hidhost"
  44 #define BT_PROFILE_PAN_ID "pan"
  45
  46
  47 /** Bluetooth Address */
  48 typedef struct {
  49     uint8_t address[6];
  50 } __attribute__((packed))bt_bdaddr_t;
  51
  52 /** Bluetooth Device Name */
  53 typedef struct {
  54     uint8_t name[248];
  55 } __attribute__((packed))bt_bdname_t;
  56
  57 /** Bluetooth Adapter Visibility Modes*/
  58 typedef enum {
  59     BT_SCAN_MODE_NONE,
  60     BT_SCAN_MODE_CONNECTABLE,
  61     BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE
  62 } bt_scan_mode_t;
  63
  64 /** Bluetooth Adapter State */
  65 typedef enum {
  66     BT_STATE_OFF,
  67     BT_STATE_ON
  68 }   bt_state_t;
  69
  70 /** Bluetooth Error Status */
  71 /** We need to build on this */
  72
  73 typedef enum {
  74     BT_STATUS_SUCCESS,
  75     BT_STATUS_FAIL,
  76     BT_STATUS_NOT_READY,
  77     BT_STATUS_NOMEM,
  78     BT_STATUS_BUSY,
  79     BT_STATUS_DONE,        /* request already completed */
  80     BT_STATUS_UNSUPPORTED,
  81     BT_STATUS_PARM_INVALID,
  82     BT_STATUS_UNHANDLED,
  83     BT_STATUS_AUTH_FAILURE,
  84     BT_STATUS_RMT_DEV_DOWN
  85
  86 } bt_status_t;
  87
  88 /** Bluetooth PinKey Code */
  89 typedef struct {
  90     uint8_t pin[16];
  91 } __attribute__((packed))bt_pin_code_t;
  92
  93 /** Bluetooth Adapter Discovery state */
  94 typedef enum {
  95     BT_DISCOVERY_STOPPED,
  96     BT_DISCOVERY_STARTED
  97 } bt_discovery_state_t;
  98
  99 /** Bluetooth ACL connection state */
 100 typedef enum {
 101     BT_ACL_STATE_CONNECTED,
 102     BT_ACL_STATE_DISCONNECTED
 103 } bt_acl_state_t;
 104
 105 /** Bluetooth 128-bit UUID */
 106 typedef struct {
 107    uint8_t uu[16];
 108 } bt_uuid_t;
 109
 110 /** Bluetooth SDP service record */
 111 typedef struct
 112 {
 113    bt_uuid_t uuid;
 114    uint16_t channel;
 115    char name[256]; // what's the maximum length
 116 } bt_service_record_t;
 117
 118 /* Bluetooth Adapter and Remote Device property types */
 119 typedef enum {
 120     /* Properties common to both adapter and remote device */
 121     /**
 122      * Description - Bluetooth Device Name
 123      * Access mode - Adapter name can be GET/SET. Remote device can be GET
 124      * Data type   - bt_bdname_t
 125      */
 126     BT_PROPERTY_BDNAME = 0x1,
 127     /**
 128      * Description - Bluetooth Device Address
 129      * Access mode - Only GET.
 130      * Data type   - bt_bdaddr_t
 131      */
 132     BT_PROPERTY_BDADDR,
 133     /**
 134      * Description - Bluetooth Service 128-bit UUIDs
 135      * Access mode - Only GET.
 136      * Data type   - Array of bt_uuid_t (Array size inferred from property length).
 137      */
 138     BT_PROPERTY_UUIDS,
 139     /**
 140      * Description - Bluetooth Class of Device as found in Assigned Numbers
 141      * Access mode - Only GET.
 142      * Data type   - uint32_t.
 143      */
 144     BT_PROPERTY_CLASS_OF_DEVICE,
 145     /**
 146      * Description - Device Type - BREDR, BLE or DUAL Mode
 147      * Access mode - Only GET.
 148      * Data type   - bt_device_type_t
 149      */
 150     BT_PROPERTY_TYPE_OF_DEVICE,
 151     /**
 152      * Description - Bluetooth Service Record
 153      * Access mode - Only GET.
 154      * Data type   - bt_service_record_t
 155      */
 156     BT_PROPERTY_SERVICE_RECORD,
 157
 158     /* Properties unique to adapter */
 159     /**
 160      * Description - Bluetooth Adapter scan mode
 161      * Access mode - GET and SET
 162      * Data type   - bt_scan_mode_t.
 163      */
 164     BT_PROPERTY_ADAPTER_SCAN_MODE,
 165     /**
 166      * Description - List of bonded devices
 167      * Access mode - Only GET.
 168      * Data type   - Array of bt_bdaddr_t of the bonded remote devices
 169      *               (Array size inferred from property length).
 170      */
 171     BT_PROPERTY_ADAPTER_BONDED_DEVICES,
 172     /**
 173      * Description - Bluetooth Adapter Discovery timeout (in seconds)
 174      * Access mode - GET and SET
 175      * Data type   - uint32_t
 176      */
 177     BT_PROPERTY_ADAPTER_DISCOVERY_TIMEOUT,
 178
 179     /* Properties unique to remote device */
 180     /**
 181      * Description - User defined friendly name of the remote device
 182      * Access mode - GET and SET
 183      * Data type   - bt_bdname_t.
 184      */
 185     BT_PROPERTY_REMOTE_FRIENDLY_NAME,
 186     /**
 187      * Description - RSSI value of the inquired remote device
 188      * Access mode - Only GET.
 189      * Data type   - int32_t.
 190      */
 191     BT_PROPERTY_REMOTE_RSSI,
 192
 193     BT_PROPERTY_REMOTE_DEVICE_TIMESTAMP = 0xFF,
 194 } bt_property_type_t;
 195
 196 /** Bluetooth Adapter Property data structure */
 197 typedef struct
 198 {
 199     bt_property_type_t type;
 200     int len;
 201     void *val;
 202 } bt_property_t;
 203
 204 /** Bluetooth Device Type */
 205 typedef enum {
 206     BT_DEVICE_DEVTYPE_BREDR = 0x1,
 207     BT_DEVICE_DEVTYPE_BLE,
 208     BT_DEVICE_DEVTYPE_DUAL
 209 } bt_device_type_t;
 210 /** Bluetooth Bond state */
 211 typedef enum {
 212     BT_BOND_STATE_NONE,
 213     BT_BOND_STATE_BONDING,
 214     BT_BOND_STATE_BONDED
 215 } bt_bond_state_t;
 216
 217 /** Bluetooth SSP Bonding Variant */
 218 typedef enum {
 219     BT_SSP_VARIANT_PASSKEY_CONFIRMATION,
 220     BT_SSP_VARIANT_PASSKEY_ENTRY,
 221     BT_SSP_VARIANT_CONSENT,
 222     BT_SSP_VARIANT_PASSKEY_NOTIFICATION
 223 } bt_ssp_variant_t;
 224
 225 #define BT_MAX_NUM_UUIDS 32
 226
 227 /** Bluetooth Interface callbacks */
 228
 229 /** Bluetooth Enable/Disable Callback. */
 230 typedef void (*adapter_state_changed_callback)(bt_state_t state);
 231
 232 /** GET/SET Adapter Properties callback */
 233 /* TODO: For the GET/SET property APIs/callbacks, we may need a session
 234  * identifier to associate the call with the callback. This would be needed
 235  * whenever more than one simultaneous instance of the same adapter_type
 236  * is get/set.
 237  *
 238  * If this is going to be handled in the Java framework, then we do not need
 239  * to manage sessions here.
 240  */
 241 typedef void (*adapter_properties_callback)(bt_status_t status,
 242                                                int num_properties,
 243                                                bt_property_t *properties);
 244
 245 /** GET/SET Remote Device Properties callback */
 246 /** TODO: For remote device properties, do not see a need to get/set
 247  * multiple properties - num_properties shall be 1
 248  */
 249 typedef void (*remote_device_properties_callback)(bt_status_t status,
 250                                                        bt_bdaddr_t *bd_addr,
 251                                                        int num_properties,
 252                                                        bt_property_t *properties);
 253
 254 /** New device discovered callback */
 255 /** If EIR data is not present, then BD_NAME and RSSI shall be NULL and -1
 256  * respectively */
 257 typedef void (*device_found_callback)(int num_properties,
 258                                          bt_property_t *properties);
 259
 260 /** Discovery state changed callback */
 261 typedef void (*discovery_state_changed_callback)(bt_discovery_state_t state);
 262
 263 /** Bluetooth Legacy PinKey Request callback */
 264 typedef void (*pin_request_callback)(bt_bdaddr_t *remote_bd_addr,
 265                                         bt_bdname_t *bd_name, uint32_t cod);
 266
 267 /** Bluetooth SSP Request callback - Just Works & Numeric Comparison*/
 268 /** pass_key - Shall be 0 for BT_SSP_PAIRING_VARIANT_CONSENT &
 269  *  BT_SSP_PAIRING_PASSKEY_ENTRY */
 270 /* TODO: Passkey request callback shall not be needed for devices with display
 271  * capability. We still need support this in the stack for completeness */
 272 typedef void (*ssp_request_callback)(bt_bdaddr_t *remote_bd_addr,
 273                                         bt_bdname_t *bd_name,
 274                                         uint32_t cod,
 275                                         bt_ssp_variant_t pairing_variant,
 276                                      uint32_t pass_key);
 277
 278 /** Bluetooth Bond state changed callback */
 279 /* Invoked in response to create_bond, cancel_bond or remove_bond */
 280 typedef void (*bond_state_changed_callback)(bt_status_t status,
 281                                                bt_bdaddr_t *remote_bd_addr,
 282                                                bt_bond_state_t state);
 283
 284 /** Bluetooth ACL connection state changed callback */
 285 typedef void (*acl_state_changed_callback)(bt_status_t status, bt_bdaddr_t *remote_bd_addr,
 286                                             bt_acl_state_t state);
 287
 288 typedef enum {
 289     ASSOCIATE_JVM,
 290     DISASSOCIATE_JVM
 291 } bt_cb_thread_evt;
 292
 293 /** Thread Associate/Disassociate JVM Callback */
 294 /* Callback that is invoked by the callback thread to allow upper layer to attach/detach to/from
 295  * the JVM */
 296 typedef void (*callback_thread_event)(bt_cb_thread_evt evt);
 297
 298 /** Bluetooth Test Mode Callback */
 299 /* Receive any HCI event from controller. Must be in DUT Mode for this callback to be received */
 300 typedef void (*dut_mode_recv_callback)(uint16_t opcode, uint8_t *buf, uint8_t len);
 301
 302 /** TODO: Add callbacks for Link Up/Down and other generic
 303   *  notifications/callbacks */
 304
 305 /** Bluetooth DM callback structure. */
 306 typedef struct {
 307     /** set to sizeof(bt_callbacks_t) */
 308     size_t size;
 309     adapter_state_changed_callback adapter_state_changed_cb;
 310     adapter_properties_callback adapter_properties_cb;
 311     remote_device_properties_callback remote_device_properties_cb;
 312     device_found_callback device_found_cb;
 313     discovery_state_changed_callback discovery_state_changed_cb;
 314     pin_request_callback pin_request_cb;
 315     ssp_request_callback ssp_request_cb;
 316     bond_state_changed_callback bond_state_changed_cb;
 317     acl_state_changed_callback acl_state_changed_cb;
 318     callback_thread_event thread_evt_cb;
 319     dut_mode_recv_callback dut_mode_recv_cb;
 320 } bt_callbacks_t;
 321
 322 /** NOTE: By default, no profiles are initialized at the time of init/enable.
 323  *  Whenever the application invokes the 'init' API of a profile, then one of
 324  *  the following shall occur:
 325  *
 326  *    1.) If Bluetooth is not enabled, then the Bluetooth core shall mark the
 327  *        profile as enabled. Subsequently, when the application invokes the
 328  *        Bluetooth 'enable', as part of the enable sequence the profile that were
 329  *        marked shall be enabled by calling appropriate stack APIs. The
 330  *        'adapter_properties_cb' shall return the list of UUIDs of the
 331  *        enabled profiles.
 332  *
 333  *    2.) If Bluetooth is enabled, then the Bluetooth core shall invoke the stack
 334  *        profile API to initialize the profile and trigger a
 335  *        'adapter_properties_cb' with the current list of UUIDs including the
 336  *        newly added profile's UUID.
 337  *
 338  *   The reverse shall occur whenever the profile 'cleanup' APIs are invoked
 339  */
 340
 341 /** Represents the standard Bluetooth DM interface. */
 342 typedef struct {
 343     /** set to sizeof(bt_interface_t) */
 344     size_t size;
 345     /**
 346      * Opens the interface and provides the callback routines
 347      * to the implemenation of this interface.
 348      */
 349     int (*init)(bt_callbacks_t* callbacks );
 350
 351     /** Enable Bluetooth. */
 352     int (*enable)(void);
 353
 354     /** Disable Bluetooth. */
 355     int (*disable)(void);
 356
 357     /** Closes the interface. */
 358     void (*cleanup)(void);
 359
 360     /** Get all Bluetooth Adapter properties at init */
 361     int (*get_adapter_properties)(void);
 362
 363     /** Get Bluetooth Adapter property of 'type' */
 364     int (*get_adapter_property)(bt_property_type_t type);
 365
 366     /** Set Bluetooth Adapter property of 'type' */
 367     /* Based on the type, val shall be one of
 368      * bt_bdaddr_t or bt_bdname_t or bt_scanmode_t etc
 369      */
 370     int (*set_adapter_property)(const bt_property_t *property);
 371
 372     /** Get all Remote Device properties */
 373     int (*get_remote_device_properties)(bt_bdaddr_t *remote_addr);
 374
 375     /** Get Remote Device property of 'type' */
 376     int (*get_remote_device_property)(bt_bdaddr_t *remote_addr,
 377                                       bt_property_type_t type);
 378
 379     /** Set Remote Device property of 'type' */
 380     int (*set_remote_device_property)(bt_bdaddr_t *remote_addr,
 381                                       const bt_property_t *property);
 382
 383     /** Get Remote Device's service record  for the given UUID */
 384     int (*get_remote_service_record)(bt_bdaddr_t *remote_addr,
 385                                      bt_uuid_t *uuid);
 386
 387     /** Start SDP to get remote services */
 388     int (*get_remote_services)(bt_bdaddr_t *remote_addr);
 389
 390     /** Start Discovery */
 391     int (*start_discovery)(void);
 392
 393     /** Cancel Discovery */
 394     int (*cancel_discovery)(void);
 395
 396     /** Create Bluetooth Bonding */
 397     int (*create_bond)(const bt_bdaddr_t *bd_addr);
 398
 399     /** Remove Bond */
 400     int (*remove_bond)(const bt_bdaddr_t *bd_addr);
 401
 402     /** Cancel Bond */
 403     int (*cancel_bond)(const bt_bdaddr_t *bd_addr);
 404
 405     /** BT Legacy PinKey Reply */
 406     /** If accept==FALSE, then pin_len and pin_code shall be 0x0 */
 407     int (*pin_reply)(const bt_bdaddr_t *bd_addr, uint8_t accept,
 408                      uint8_t pin_len, bt_pin_code_t *pin_code);
 409
 410     /** BT SSP Reply - Just Works, Numeric Comparison and Passkey
 411      * passkey shall be zero for BT_SSP_VARIANT_PASSKEY_COMPARISON &
 412      * BT_SSP_VARIANT_CONSENT
 413      * For BT_SSP_VARIANT_PASSKEY_ENTRY, if accept==FALSE, then passkey
 414      * shall be zero */
 415     int (*ssp_reply)(const bt_bdaddr_t *bd_addr, bt_ssp_variant_t variant,
 416                      uint8_t accept, uint32_t passkey);
 417
 418     /** Get Bluetooth profile interface */
 419     const void* (*get_profile_interface) (const char *profile_id);
 420
 421     /** Bluetooth Test Mode APIs - Bluetooth must be enabled for these APIs */
 422     /* Configure DUT Mode - Use this mode to enter/exit DUT mode */
 423     int (*dut_mode_configure)(uint8_t enable);
 424
 425     /* Send any test HCI (vendor-specific) command to the controller. Must be in DUT Mode */
 426     int (*dut_mode_send)(uint16_t opcode, uint8_t *buf, uint8_t len);
 427 } bt_interface_t;
 428
 429 /** TODO: Need to add APIs for Service Discovery, Service authorization and
 430   *       connection management. Also need to add APIs for configuring
 431   *       properties of remote bonded devices such as name, UUID etc. */
 432
 433 typedef struct {
 434     struct hw_device_t common;
 435     const bt_interface_t* (*get_bluetooth_interface)();
 436 } bluetooth_device_t;
 437
 438 typedef bluetooth_device_t bluetooth_module_t;
 439 __END_DECLS
 440
 441 #endif /* ANDROID_INCLUDE_BLUETOOTH_H */