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 <stdbool.h> 21 #include <stdint.h> 22 #include <sys/cdefs.h> 23 #include <sys/types.h> 24 25 #include "avrcp/avrcp.h" 26 #include "bluetooth/uuid.h" 27 #include "raw_address.h" 28 29 /** 30 * The Bluetooth Hardware Module ID 31 */ 32 33 #define BT_HARDWARE_MODULE_ID "bluetooth" 34 #define BT_STACK_MODULE_ID "bluetooth" 35 36 /** Bluetooth profile interface IDs */ 37 #define BT_PROFILE_HANDSFREE_ID "handsfree" 38 #define BT_PROFILE_HANDSFREE_CLIENT_ID "handsfree_client" 39 #define BT_PROFILE_ADVANCED_AUDIO_ID "a2dp" 40 #define BT_PROFILE_ADVANCED_AUDIO_SINK_ID "a2dp_sink" 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_HIDDEV_ID "hiddev" 45 #define BT_PROFILE_PAN_ID "pan" 46 #define BT_PROFILE_MAP_CLIENT_ID "map_client" 47 #define BT_PROFILE_SDP_CLIENT_ID "sdp" 48 #define BT_PROFILE_GATT_ID "gatt" 49 #define BT_PROFILE_AV_RC_ID "avrcp" 50 #define BT_PROFILE_AV_RC_CTRL_ID "avrcp_ctrl" 51 #define BT_PROFILE_HEARING_AID_ID "hearing_aid" 52 53 /** Bluetooth test interface IDs */ 54 #define BT_TEST_INTERFACE_MCAP_ID "mcap_test" 55 56 /** Bluetooth Device Name */ 57 typedef struct { uint8_t name[249]; } __attribute__((packed)) bt_bdname_t; 58 59 /** Bluetooth Adapter Visibility Modes*/ 60 typedef enum { 61 BT_SCAN_MODE_NONE, 62 BT_SCAN_MODE_CONNECTABLE, 63 BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE 64 } bt_scan_mode_t; 65 66 /** Bluetooth Adapter State */ 67 typedef enum { BT_STATE_OFF, BT_STATE_ON } bt_state_t; 68 69 /** Bluetooth Error Status */ 70 /** We need to build on this */ 71 72 typedef enum { 73 BT_STATUS_SUCCESS, 74 BT_STATUS_FAIL, 75 BT_STATUS_NOT_READY, 76 BT_STATUS_NOMEM, 77 BT_STATUS_BUSY, 78 BT_STATUS_DONE, /* request already completed */ 79 BT_STATUS_UNSUPPORTED, 80 BT_STATUS_PARM_INVALID, 81 BT_STATUS_UNHANDLED, 82 BT_STATUS_AUTH_FAILURE, 83 BT_STATUS_RMT_DEV_DOWN, 84 BT_STATUS_AUTH_REJECTED, 85 BT_STATUS_JNI_ENVIRONMENT_ERROR, 86 BT_STATUS_JNI_THREAD_ATTACH_ERROR, 87 BT_STATUS_WAKELOCK_ERROR 88 } bt_status_t; 89 90 /** Bluetooth PinKey Code */ 91 typedef struct { uint8_t pin[16]; } __attribute__((packed)) bt_pin_code_t; 92 93 typedef struct { 94 uint8_t status; 95 uint8_t ctrl_state; /* stack reported state */ 96 uint64_t tx_time; /* in ms */ 97 uint64_t rx_time; /* in ms */ 98 uint64_t idle_time; /* in ms */ 99 uint64_t energy_used; /* a product of mA, V and ms */ 100 } __attribute__((packed)) bt_activity_energy_info; 101 102 typedef struct { 103 int32_t app_uid; 104 uint64_t tx_bytes; 105 uint64_t rx_bytes; 106 } __attribute__((packed)) bt_uid_traffic_t; 107 108 /** Bluetooth Adapter Discovery state */ 109 typedef enum { 110 BT_DISCOVERY_STOPPED, 111 BT_DISCOVERY_STARTED 112 } bt_discovery_state_t; 113 114 /** Bluetooth ACL connection state */ 115 typedef enum { 116 BT_ACL_STATE_CONNECTED, 117 BT_ACL_STATE_DISCONNECTED 118 } bt_acl_state_t; 119 120 /** Bluetooth SDP service record */ 121 typedef struct { 122 bluetooth::Uuid uuid; 123 uint16_t channel; 124 char name[256]; // what's the maximum length 125 } bt_service_record_t; 126 127 /** Bluetooth Remote Version info */ 128 typedef struct { 129 int version; 130 int sub_ver; 131 int manufacturer; 132 } bt_remote_version_t; 133 134 typedef struct { 135 uint16_t version_supported; 136 uint8_t local_privacy_enabled; 137 uint8_t max_adv_instance; 138 uint8_t rpa_offload_supported; 139 uint8_t max_irk_list_size; 140 uint8_t max_adv_filter_supported; 141 uint8_t activity_energy_info_supported; 142 uint16_t scan_result_storage_size; 143 uint16_t total_trackable_advertisers; 144 bool extended_scan_support; 145 bool debug_logging_supported; 146 bool le_2m_phy_supported; 147 bool le_coded_phy_supported; 148 bool le_extended_advertising_supported; 149 bool le_periodic_advertising_supported; 150 uint16_t le_maximum_advertising_data_length; 151 } bt_local_le_features_t; 152 153 /* Bluetooth Adapter and Remote Device property types */ 154 typedef enum { 155 /* Properties common to both adapter and remote device */ 156 /** 157 * Description - Bluetooth Device Name 158 * Access mode - Adapter name can be GET/SET. Remote device can be GET 159 * Data type - bt_bdname_t 160 */ 161 BT_PROPERTY_BDNAME = 0x1, 162 /** 163 * Description - Bluetooth Device Address 164 * Access mode - Only GET. 165 * Data type - RawAddress 166 */ 167 BT_PROPERTY_BDADDR, 168 /** 169 * Description - Bluetooth Service 128-bit UUIDs 170 * Access mode - Only GET. 171 * Data type - Array of bluetooth::Uuid (Array size inferred from property 172 * length). 173 */ 174 BT_PROPERTY_UUIDS, 175 /** 176 * Description - Bluetooth Class of Device as found in Assigned Numbers 177 * Access mode - Only GET. 178 * Data type - uint32_t. 179 */ 180 BT_PROPERTY_CLASS_OF_DEVICE, 181 /** 182 * Description - Device Type - BREDR, BLE or DUAL Mode 183 * Access mode - Only GET. 184 * Data type - bt_device_type_t 185 */ 186 BT_PROPERTY_TYPE_OF_DEVICE, 187 /** 188 * Description - Bluetooth Service Record 189 * Access mode - Only GET. 190 * Data type - bt_service_record_t 191 */ 192 BT_PROPERTY_SERVICE_RECORD, 193 194 /* Properties unique to adapter */ 195 /** 196 * Description - Bluetooth Adapter scan mode 197 * Access mode - GET and SET 198 * Data type - bt_scan_mode_t. 199 */ 200 BT_PROPERTY_ADAPTER_SCAN_MODE, 201 /** 202 * Description - List of bonded devices 203 * Access mode - Only GET. 204 * Data type - Array of RawAddress of the bonded remote devices 205 * (Array size inferred from property length). 206 */ 207 BT_PROPERTY_ADAPTER_BONDED_DEVICES, 208 /** 209 * Description - Bluetooth Adapter Discovery timeout (in seconds) 210 * Access mode - GET and SET 211 * Data type - uint32_t 212 */ 213 BT_PROPERTY_ADAPTER_DISCOVERY_TIMEOUT, 214 215 /* Properties unique to remote device */ 216 /** 217 * Description - User defined friendly name of the remote device 218 * Access mode - GET and SET 219 * Data type - bt_bdname_t. 220 */ 221 BT_PROPERTY_REMOTE_FRIENDLY_NAME, 222 /** 223 * Description - RSSI value of the inquired remote device 224 * Access mode - Only GET. 225 * Data type - int8_t. 226 */ 227 BT_PROPERTY_REMOTE_RSSI, 228 /** 229 * Description - Remote version info 230 * Access mode - SET/GET. 231 * Data type - bt_remote_version_t. 232 */ 233 234 BT_PROPERTY_REMOTE_VERSION_INFO, 235 236 /** 237 * Description - Local LE features 238 * Access mode - GET. 239 * Data type - bt_local_le_features_t. 240 */ 241 BT_PROPERTY_LOCAL_LE_FEATURES, 242 243 BT_PROPERTY_REMOTE_DEVICE_TIMESTAMP = 0xFF, 244 } bt_property_type_t; 245 246 /** Bluetooth Adapter Property data structure */ 247 typedef struct { 248 bt_property_type_t type; 249 int len; 250 void* val; 251 } bt_property_t; 252 253 /** Bluetooth Out Of Band data for bonding */ 254 typedef struct { 255 uint8_t le_bt_dev_addr[7]; /* LE Bluetooth Device Address */ 256 uint8_t c192[16]; /* Simple Pairing Hash C-192 */ 257 uint8_t r192[16]; /* Simple Pairing Randomizer R-192 */ 258 uint8_t c256[16]; /* Simple Pairing Hash C-256 */ 259 uint8_t r256[16]; /* Simple Pairing Randomizer R-256 */ 260 uint8_t sm_tk[16]; /* Security Manager TK Value */ 261 uint8_t le_sc_c[16]; /* LE Secure Connections Confirmation Value */ 262 uint8_t le_sc_r[16]; /* LE Secure Connections Random Value */ 263 } bt_out_of_band_data_t; 264 265 /** Bluetooth Device Type */ 266 typedef enum { 267 BT_DEVICE_DEVTYPE_BREDR = 0x1, 268 BT_DEVICE_DEVTYPE_BLE, 269 BT_DEVICE_DEVTYPE_DUAL 270 } bt_device_type_t; 271 /** Bluetooth Bond state */ 272 typedef enum { 273 BT_BOND_STATE_NONE, 274 BT_BOND_STATE_BONDING, 275 BT_BOND_STATE_BONDED 276 } bt_bond_state_t; 277 278 /** Bluetooth SSP Bonding Variant */ 279 typedef enum { 280 BT_SSP_VARIANT_PASSKEY_CONFIRMATION, 281 BT_SSP_VARIANT_PASSKEY_ENTRY, 282 BT_SSP_VARIANT_CONSENT, 283 BT_SSP_VARIANT_PASSKEY_NOTIFICATION 284 } bt_ssp_variant_t; 285 286 #define BT_MAX_NUM_UUIDS 32 287 288 /** Bluetooth Interface callbacks */ 289 290 /** Bluetooth Enable/Disable Callback. */ 291 typedef void (*adapter_state_changed_callback)(bt_state_t state); 292 293 /** GET/SET Adapter Properties callback */ 294 /* TODO: For the GET/SET property APIs/callbacks, we may need a session 295 * identifier to associate the call with the callback. This would be needed 296 * whenever more than one simultaneous instance of the same adapter_type 297 * is get/set. 298 * 299 * If this is going to be handled in the Java framework, then we do not need 300 * to manage sessions here. 301 */ 302 typedef void (*adapter_properties_callback)(bt_status_t status, 303 int num_properties, 304 bt_property_t* properties); 305 306 /** GET/SET Remote Device Properties callback */ 307 /** TODO: For remote device properties, do not see a need to get/set 308 * multiple properties - num_properties shall be 1 309 */ 310 typedef void (*remote_device_properties_callback)(bt_status_t status, 311 RawAddress* bd_addr, 312 int num_properties, 313 bt_property_t* properties); 314 315 /** New device discovered callback */ 316 /** If EIR data is not present, then BD_NAME and RSSI shall be NULL and -1 317 * respectively */ 318 typedef void (*device_found_callback)(int num_properties, 319 bt_property_t* properties); 320 321 /** Discovery state changed callback */ 322 typedef void (*discovery_state_changed_callback)(bt_discovery_state_t state); 323 324 /** Bluetooth Legacy PinKey Request callback */ 325 typedef void (*pin_request_callback)(RawAddress* remote_bd_addr, 326 bt_bdname_t* bd_name, uint32_t cod, 327 bool min_16_digit); 328 329 /** Bluetooth SSP Request callback - Just Works & Numeric Comparison*/ 330 /** pass_key - Shall be 0 for BT_SSP_PAIRING_VARIANT_CONSENT & 331 * BT_SSP_PAIRING_PASSKEY_ENTRY */ 332 /* TODO: Passkey request callback shall not be needed for devices with display 333 * capability. We still need support this in the stack for completeness */ 334 typedef void (*ssp_request_callback)(RawAddress* remote_bd_addr, 335 bt_bdname_t* bd_name, uint32_t cod, 336 bt_ssp_variant_t pairing_variant, 337 uint32_t pass_key); 338 339 /** Bluetooth Bond state changed callback */ 340 /* Invoked in response to create_bond, cancel_bond or remove_bond */ 341 typedef void (*bond_state_changed_callback)(bt_status_t status, 342 RawAddress* remote_bd_addr, 343 bt_bond_state_t state); 344 345 /** Bluetooth ACL connection state changed callback */ 346 typedef void (*acl_state_changed_callback)(bt_status_t status, 347 RawAddress* remote_bd_addr, 348 bt_acl_state_t state); 349 350 typedef enum { ASSOCIATE_JVM, DISASSOCIATE_JVM } bt_cb_thread_evt; 351 352 /** Thread Associate/Disassociate JVM Callback */ 353 /* Callback that is invoked by the callback thread to allow upper layer to 354 * attach/detach to/from the JVM */ 355 typedef void (*callback_thread_event)(bt_cb_thread_evt evt); 356 357 /** Bluetooth Test Mode Callback */ 358 /* Receive any HCI event from controller. Must be in DUT Mode for this callback 359 * to be received */ 360 typedef void (*dut_mode_recv_callback)(uint16_t opcode, uint8_t* buf, 361 uint8_t len); 362 363 /* LE Test mode callbacks 364 * This callback shall be invoked whenever the le_tx_test, le_rx_test or 365 * le_test_end is invoked The num_packets is valid only for le_test_end command 366 */ 367 typedef void (*le_test_mode_callback)(bt_status_t status, uint16_t num_packets); 368 369 /** Callback invoked when energy details are obtained */ 370 /* Ctrl_state-Current controller state-Active-1,scan-2,or idle-3 state as 371 * defined by HCI spec. If the ctrl_state value is 0, it means the API call 372 * failed Time values-In milliseconds as returned by the controller Energy 373 * used-Value as returned by the controller Status-Provides the status of the 374 * read_energy_info API call uid_data provides an array of bt_uid_traffic_t, 375 * where the array is terminated by an element with app_uid set to -1. 376 */ 377 typedef void (*energy_info_callback)(bt_activity_energy_info* energy_info, 378 bt_uid_traffic_t* uid_data); 379 380 /** TODO: Add callbacks for Link Up/Down and other generic 381 * notifications/callbacks */ 382 383 /** Bluetooth DM callback structure. */ 384 typedef struct { 385 /** set to sizeof(bt_callbacks_t) */ 386 size_t size; 387 adapter_state_changed_callback adapter_state_changed_cb; 388 adapter_properties_callback adapter_properties_cb; 389 remote_device_properties_callback remote_device_properties_cb; 390 device_found_callback device_found_cb; 391 discovery_state_changed_callback discovery_state_changed_cb; 392 pin_request_callback pin_request_cb; 393 ssp_request_callback ssp_request_cb; 394 bond_state_changed_callback bond_state_changed_cb; 395 acl_state_changed_callback acl_state_changed_cb; 396 callback_thread_event thread_evt_cb; 397 dut_mode_recv_callback dut_mode_recv_cb; 398 le_test_mode_callback le_test_mode_cb; 399 energy_info_callback energy_info_cb; 400 } bt_callbacks_t; 401 402 typedef void (*alarm_cb)(void* data); 403 typedef bool (*set_wake_alarm_callout)(uint64_t delay_millis, bool should_wake, 404 alarm_cb cb, void* data); 405 typedef int (*acquire_wake_lock_callout)(const char* lock_name); 406 typedef int (*release_wake_lock_callout)(const char* lock_name); 407 408 /** The set of functions required by bluedroid to set wake alarms and 409 * grab wake locks. This struct is passed into the stack through the 410 * |set_os_callouts| function on |bt_interface_t|. 411 */ 412 typedef struct { 413 /* set to sizeof(bt_os_callouts_t) */ 414 size_t size; 415 416 set_wake_alarm_callout set_wake_alarm; 417 acquire_wake_lock_callout acquire_wake_lock; 418 release_wake_lock_callout release_wake_lock; 419 } bt_os_callouts_t; 420 421 /** NOTE: By default, no profiles are initialized at the time of init/enable. 422 * Whenever the application invokes the 'init' API of a profile, then one of 423 * the following shall occur: 424 * 425 * 1.) If Bluetooth is not enabled, then the Bluetooth core shall mark the 426 * profile as enabled. Subsequently, when the application invokes the 427 * Bluetooth 'enable', as part of the enable sequence the profile that 428 * were marked shall be enabled by calling appropriate stack APIs. The 429 * 'adapter_properties_cb' shall return the list of UUIDs of the 430 * enabled profiles. 431 * 432 * 2.) If Bluetooth is enabled, then the Bluetooth core shall invoke the 433 * stack profile API to initialize the profile and trigger a 434 * 'adapter_properties_cb' with the current list of UUIDs including the 435 * newly added profile's UUID. 436 * 437 * The reverse shall occur whenever the profile 'cleanup' APIs are invoked 438 */ 439 440 /** Represents the standard Bluetooth DM interface. */ 441 typedef struct { 442 /** set to sizeof(bt_interface_t) */ 443 size_t size; 444 /** 445 * Opens the interface and provides the callback routines 446 * to the implemenation of this interface. 447 */ 448 int (*init)(bt_callbacks_t* callbacks); 449 450 /** Enable Bluetooth. */ 451 int (*enable)(bool guest_mode); 452 453 /** Disable Bluetooth. */ 454 int (*disable)(void); 455 456 /** Closes the interface. */ 457 void (*cleanup)(void); 458 459 /** Get all Bluetooth Adapter properties at init */ 460 int (*get_adapter_properties)(void); 461 462 /** Get Bluetooth Adapter property of 'type' */ 463 int (*get_adapter_property)(bt_property_type_t type); 464 465 /** Set Bluetooth Adapter property of 'type' */ 466 /* Based on the type, val shall be one of 467 * RawAddress or bt_bdname_t or bt_scanmode_t etc 468 */ 469 int (*set_adapter_property)(const bt_property_t* property); 470 471 /** Get all Remote Device properties */ 472 int (*get_remote_device_properties)(RawAddress* remote_addr); 473 474 /** Get Remote Device property of 'type' */ 475 int (*get_remote_device_property)(RawAddress* remote_addr, 476 bt_property_type_t type); 477 478 /** Set Remote Device property of 'type' */ 479 int (*set_remote_device_property)(RawAddress* remote_addr, 480 const bt_property_t* property); 481 482 /** Get Remote Device's service record for the given UUID */ 483 int (*get_remote_service_record)(const RawAddress& remote_addr, 484 const bluetooth::Uuid& uuid); 485 486 /** Start SDP to get remote services */ 487 int (*get_remote_services)(RawAddress* remote_addr); 488 489 /** Start Discovery */ 490 int (*start_discovery)(void); 491 492 /** Cancel Discovery */ 493 int (*cancel_discovery)(void); 494 495 /** Create Bluetooth Bonding */ 496 int (*create_bond)(const RawAddress* bd_addr, int transport); 497 498 /** Create Bluetooth Bond using out of band data */ 499 int (*create_bond_out_of_band)(const RawAddress* bd_addr, int transport, 500 const bt_out_of_band_data_t* oob_data); 501 502 /** Remove Bond */ 503 int (*remove_bond)(const RawAddress* bd_addr); 504 505 /** Cancel Bond */ 506 int (*cancel_bond)(const RawAddress* bd_addr); 507 508 /** 509 * Get the connection status for a given remote device. 510 * return value of 0 means the device is not connected, 511 * non-zero return status indicates an active connection. 512 */ 513 int (*get_connection_state)(const RawAddress* bd_addr); 514 515 /** BT Legacy PinKey Reply */ 516 /** If accept==FALSE, then pin_len and pin_code shall be 0x0 */ 517 int (*pin_reply)(const RawAddress* bd_addr, uint8_t accept, uint8_t pin_len, 518 bt_pin_code_t* pin_code); 519 520 /** BT SSP Reply - Just Works, Numeric Comparison and Passkey 521 * passkey shall be zero for BT_SSP_VARIANT_PASSKEY_COMPARISON & 522 * BT_SSP_VARIANT_CONSENT 523 * For BT_SSP_VARIANT_PASSKEY_ENTRY, if accept==FALSE, then passkey 524 * shall be zero */ 525 int (*ssp_reply)(const RawAddress* bd_addr, bt_ssp_variant_t variant, 526 uint8_t accept, uint32_t passkey); 527 528 /** Get Bluetooth profile interface */ 529 const void* (*get_profile_interface)(const char* profile_id); 530 531 /** Bluetooth Test Mode APIs - Bluetooth must be enabled for these APIs */ 532 /* Configure DUT Mode - Use this mode to enter/exit DUT mode */ 533 int (*dut_mode_configure)(uint8_t enable); 534 535 /* Send any test HCI (vendor-specific) command to the controller. Must be in 536 * DUT Mode */ 537 int (*dut_mode_send)(uint16_t opcode, uint8_t* buf, uint8_t len); 538 /** BLE Test Mode APIs */ 539 /* opcode MUST be one of: LE_Receiver_Test, LE_Transmitter_Test, LE_Test_End 540 */ 541 int (*le_test_mode)(uint16_t opcode, uint8_t* buf, uint8_t len); 542 543 /** Sets the OS call-out functions that bluedroid needs for alarms and wake 544 * locks. This should be called immediately after a successful |init|. 545 */ 546 int (*set_os_callouts)(bt_os_callouts_t* callouts); 547 548 /** Read Energy info details - return value indicates BT_STATUS_SUCCESS or 549 * BT_STATUS_NOT_READY Success indicates that the VSC command was sent to 550 * controller 551 */ 552 int (*read_energy_info)(); 553 554 /** 555 * Native support for dumpsys function 556 * Function is synchronous and |fd| is owned by caller. 557 * |arguments| are arguments which may affect the output, encoded as 558 * UTF-8 strings. 559 */ 560 void (*dump)(int fd, const char** arguments); 561 562 /** 563 * Native support for metrics protobuf dumping. The dumping format will be 564 * raw byte array 565 * 566 * @param output an externally allocated string to dump serialized protobuf 567 */ 568 void (*dumpMetrics)(std::string* output); 569 570 /** 571 * Clear /data/misc/bt_config.conf and erase all stored connections 572 */ 573 int (*config_clear)(void); 574 575 /** 576 * Clear (reset) the dynamic portion of the device interoperability database. 577 */ 578 void (*interop_database_clear)(void); 579 580 /** 581 * Add a new device interoperability workaround for a remote device whose 582 * first |len| bytes of the its device address match |addr|. 583 * NOTE: |feature| has to match an item defined in interop_feature_t 584 * (interop.h). 585 */ 586 void (*interop_database_add)(uint16_t feature, const RawAddress* addr, 587 size_t len); 588 589 /** 590 * Get the AvrcpTarget Service interface to interact with the Avrcp Service 591 */ 592 bluetooth::avrcp::ServiceInterface* (*get_avrcp_service)(void); 593 } bt_interface_t; 594 595 #define BLUETOOTH_INTERFACE_STRING "bluetoothInterface" 596 597 #endif /* ANDROID_INCLUDE_BLUETOOTH_H */ 598