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