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