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 
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 {
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  */
165  /**
166  * Description - Bluetooth Device Address
167  * Access mode - Only GET.
168  * Data type - bt_bdaddr_t
169  */
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  */
177  /**
178  * Description - Bluetooth Class of Device as found in Assigned Numbers
179  * Access mode - Only GET.
180  * Data type - uint32_t.
181  */
183  /**
184  * Description - Device Type - BREDR, BLE or DUAL Mode
185  * Access mode - Only GET.
186  * Data type - bt_device_type_t
187  */
189  /**
190  * Description - Bluetooth Service Record
191  * Access mode - Only GET.
192  * Data type - bt_service_record_t
193  */
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  */
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  */
210  /**
211  * Description - Bluetooth Adapter Discovery timeout (in seconds)
212  * Access mode - GET and SET
213  * Data type - uint32_t
214  */
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  */
224  /**
225  * Description - RSSI value of the inquired remote device
226  * Access mode - Only GET.
227  * Data type - int32_t.
228  */
230  /**
231  * Description - Remote version info
232  * Access mode - SET/GET.
233  * Data type - bt_remote_version_t.
234  */
235 
237 
238  /**
239  * Description - Local LE features
240  * Access mode - GET.
241  * Data type - bt_local_le_features_t.
242  */
244 
247 
248 /** Bluetooth Adapter Property data structure */
249 typedef struct
250 {
252  int len;
253  void *val;
254 } bt_property_t;
255 
256 
257 /** Bluetooth Device Type */
258 typedef enum {
263 /** Bluetooth Bond state */
264 typedef enum {
269 
270 /** Bluetooth SSP Bonding Variant */
271 typedef enum {
277 
278 #define BT_MAX_NUM_UUIDS 32
279 
280 /** Bluetooth Interface callbacks */
281 
282 /** Bluetooth Enable/Disable Callback. */
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  */
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  */
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 */
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 */
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 {
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 */
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;
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 
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)();
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)();
546 
548 __END_DECLS
549 
550 #endif /* ANDROID_INCLUDE_BLUETOOTH_H */
bt_property_type_t type
Definition: bluetooth.h:251
bt_bond_state_t
Definition: bluetooth.h:264
uint8_t local_privacy_enabled
Definition: bluetooth.h:146
void * val
Definition: bluetooth.h:253
acl_state_changed_callback acl_state_changed_cb
Definition: bluetooth.h:383
uint8_t status
Definition: bluetooth.h:102
bt_device_type_t
Definition: bluetooth.h:258
int(* release_wake_lock_callout)(const char *lock_name)
Definition: bluetooth.h:393
bt_discovery_state_t
Definition: bluetooth.h:111
set_wake_alarm_callout set_wake_alarm
Definition: bluetooth.h:403
dut_mode_recv_callback dut_mode_recv_cb
Definition: bluetooth.h:385
bond_state_changed_callback bond_state_changed_cb
Definition: bluetooth.h:382
bt_state_t
Definition: bluetooth.h:72
discovery_state_changed_callback discovery_state_changed_cb
Definition: bluetooth.h:379
le_test_mode_callback le_test_mode_cb
Definition: bluetooth.h:386
void(* alarm_cb)(void *data)
Definition: bluetooth.h:390
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:333
remote_device_properties_callback remote_device_properties_cb
Definition: bluetooth.h:377
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:302
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:436
void(* le_test_mode_callback)(bt_status_t status, uint16_t num_packets)
Definition: bluetooth.h:358
energy_info_callback energy_info_cb
Definition: bluetooth.h:387
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:392
adapter_state_changed_callback adapter_state_changed_cb
Definition: bluetooth.h:375
void(* energy_info_callback)(bt_activity_energy_info *energy_info)
Definition: bluetooth.h:366
void(* device_found_callback)(int num_properties, bt_property_t *properties)
Definition: bluetooth.h:310
release_wake_lock_callout release_wake_lock
Definition: bluetooth.h:405
bt_cb_thread_evt
Definition: bluetooth.h:341
void(* discovery_state_changed_callback)(bt_discovery_state_t state)
Definition: bluetooth.h:314
bt_ssp_variant_t
Definition: bluetooth.h:271
bt_property_type_t
Definition: bluetooth.h:157
acquire_wake_lock_callout acquire_wake_lock
Definition: bluetooth.h:404
uint8_t scan_result_storage_size_lobyte
Definition: bluetooth.h:151
uint8_t scan_result_storage_size_hibyte
Definition: bluetooth.h:152
adapter_properties_callback adapter_properties_cb
Definition: bluetooth.h:376
void(* callback_thread_event)(bt_cb_thread_evt evt)
Definition: bluetooth.h:349
uint8_t rpa_offload_supported
Definition: bluetooth.h:148
device_found_callback device_found_cb
Definition: bluetooth.h:378
uint64_t rx_time
Definition: bluetooth.h:105
uint8_t max_adv_filter_supported
Definition: bluetooth.h:150
bt_scan_mode_t
Definition: bluetooth.h:65
callback_thread_event thread_evt_cb
Definition: bluetooth.h:384
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:325
bluetooth_device_t bluetooth_module_t
Definition: bluetooth.h:547
void(* dut_mode_recv_callback)(uint16_t opcode, uint8_t *buf, uint8_t len)
Definition: bluetooth.h:353
bool(* set_wake_alarm_callout)(uint64_t delay_millis, bool should_wake, alarm_cb cb, void *data)
Definition: bluetooth.h:391
pin_request_callback pin_request_cb
Definition: bluetooth.h:380
uint8_t activity_energy_info_supported
Definition: bluetooth.h:153
void(* adapter_state_changed_callback)(bt_state_t state)
Definition: bluetooth.h:283
void(* acl_state_changed_callback)(bt_status_t status, bt_bdaddr_t *remote_bd_addr, bt_acl_state_t state)
Definition: bluetooth.h:338
ssp_request_callback ssp_request_cb
Definition: bluetooth.h:381
void(* adapter_properties_callback)(bt_status_t status, int num_properties, bt_property_t *properties)
Definition: bluetooth.h:294
void(* pin_request_callback)(bt_bdaddr_t *remote_bd_addr, bt_bdname_t *bd_name, uint32_t cod)
Definition: bluetooth.h:317