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