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