Android Hardware Abstraction Layer
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 <stdint.h>
21 #include <sys/cdefs.h>
22 #include <sys/types.h>
23 
24 #include <hardware/hardware.h>
25 
26 __BEGIN_DECLS
27 
28 /**
29  * The Bluetooth Hardware Module ID
30  */
31 
32 #define BT_HARDWARE_MODULE_ID "bluetooth"
33 #define BT_STACK_MODULE_ID "bluetooth"
34 #define BT_STACK_TEST_MODULE_ID "bluetooth_test"
35 
36 
37 /* Bluetooth profile interface IDs */
38 
39 #define BT_PROFILE_HANDSFREE_ID "handsfree"
40 #define BT_PROFILE_ADVANCED_AUDIO_ID "a2dp"
41 #define BT_PROFILE_HEALTH_ID "health"
42 #define BT_PROFILE_SOCKETS_ID "socket"
43 #define BT_PROFILE_HIDHOST_ID "hidhost"
44 #define BT_PROFILE_PAN_ID "pan"
45 
46 #define BT_PROFILE_GATT_ID "gatt"
47 #define BT_PROFILE_AV_RC_ID "avrcp"
48 
49 /** Bluetooth Address */
50 typedef struct {
51  uint8_t address[6];
52 } __attribute__((packed))bt_bdaddr_t;
53 
54 /** Bluetooth Device Name */
55 typedef struct {
56  uint8_t name[249];
57 } __attribute__((packed))bt_bdname_t;
58 
59 /** Bluetooth Adapter Visibility Modes*/
60 typedef enum {
65 
66 /** Bluetooth Adapter State */
67 typedef enum {
70 } bt_state_t;
71 
72 /** Bluetooth Error Status */
73 /** We need to build on this */
74 
75 typedef enum {
81  BT_STATUS_DONE, /* request already completed */
87 
88 } bt_status_t;
89 
90 /** Bluetooth PinKey Code */
91 typedef struct {
92  uint8_t pin[16];
93 } __attribute__((packed))bt_pin_code_t;
94 
95 /** Bluetooth Adapter Discovery state */
96 typedef enum {
100 
101 /** Bluetooth ACL connection state */
102 typedef enum {
106 
107 /** Bluetooth 128-bit UUID */
108 typedef struct {
109  uint8_t uu[16];
110 } bt_uuid_t;
111 
112 /** Bluetooth SDP service record */
113 typedef struct
114 {
116  uint16_t channel;
117  char name[256]; // what's the maximum length
119 
120 
121 /** Bluetooth Remote Version info */
122 typedef struct
123 {
124  int version;
125  int sub_ver;
128 
129 /* Bluetooth Adapter and Remote Device property types */
130 typedef enum {
131  /* Properties common to both adapter and remote device */
132  /**
133  * Description - Bluetooth Device Name
134  * Access mode - Adapter name can be GET/SET. Remote device can be GET
135  * Data type - bt_bdname_t
136  */
138  /**
139  * Description - Bluetooth Device Address
140  * Access mode - Only GET.
141  * Data type - bt_bdaddr_t
142  */
144  /**
145  * Description - Bluetooth Service 128-bit UUIDs
146  * Access mode - Only GET.
147  * Data type - Array of bt_uuid_t (Array size inferred from property length).
148  */
150  /**
151  * Description - Bluetooth Class of Device as found in Assigned Numbers
152  * Access mode - Only GET.
153  * Data type - uint32_t.
154  */
156  /**
157  * Description - Device Type - BREDR, BLE or DUAL Mode
158  * Access mode - Only GET.
159  * Data type - bt_device_type_t
160  */
162  /**
163  * Description - Bluetooth Service Record
164  * Access mode - Only GET.
165  * Data type - bt_service_record_t
166  */
168 
169  /* Properties unique to adapter */
170  /**
171  * Description - Bluetooth Adapter scan mode
172  * Access mode - GET and SET
173  * Data type - bt_scan_mode_t.
174  */
176  /**
177  * Description - List of bonded devices
178  * Access mode - Only GET.
179  * Data type - Array of bt_bdaddr_t of the bonded remote devices
180  * (Array size inferred from property length).
181  */
183  /**
184  * Description - Bluetooth Adapter Discovery timeout (in seconds)
185  * Access mode - GET and SET
186  * Data type - uint32_t
187  */
189 
190  /* Properties unique to remote device */
191  /**
192  * Description - User defined friendly name of the remote device
193  * Access mode - GET and SET
194  * Data type - bt_bdname_t.
195  */
197  /**
198  * Description - RSSI value of the inquired remote device
199  * Access mode - Only GET.
200  * Data type - int32_t.
201  */
203  /**
204  * Description - Remote version info
205  * Access mode - SET/GET.
206  * Data type - bt_remote_version_t.
207  */
208 
210 
213 
214 /** Bluetooth Adapter Property data structure */
215 typedef struct
216 {
218  int len;
219  void *val;
220 } bt_property_t;
221 
222 /** Bluetooth Device Type */
223 typedef enum {
228 /** Bluetooth Bond state */
229 typedef enum {
234 
235 /** Bluetooth SSP Bonding Variant */
236 typedef enum {
242 
243 #define BT_MAX_NUM_UUIDS 32
244 
245 /** Bluetooth Interface callbacks */
246 
247 /** Bluetooth Enable/Disable Callback. */
249 
250 /** GET/SET Adapter Properties callback */
251 /* TODO: For the GET/SET property APIs/callbacks, we may need a session
252  * identifier to associate the call with the callback. This would be needed
253  * whenever more than one simultaneous instance of the same adapter_type
254  * is get/set.
255  *
256  * If this is going to be handled in the Java framework, then we do not need
257  * to manage sessions here.
258  */
260  int num_properties,
261  bt_property_t *properties);
262 
263 /** GET/SET Remote Device Properties callback */
264 /** TODO: For remote device properties, do not see a need to get/set
265  * multiple properties - num_properties shall be 1
266  */
268  bt_bdaddr_t *bd_addr,
269  int num_properties,
270  bt_property_t *properties);
271 
272 /** New device discovered callback */
273 /** If EIR data is not present, then BD_NAME and RSSI shall be NULL and -1
274  * respectively */
275 typedef void (*device_found_callback)(int num_properties,
276  bt_property_t *properties);
277 
278 /** Discovery state changed callback */
280 
281 /** Bluetooth Legacy PinKey Request callback */
282 typedef void (*pin_request_callback)(bt_bdaddr_t *remote_bd_addr,
283  bt_bdname_t *bd_name, uint32_t cod);
284 
285 /** Bluetooth SSP Request callback - Just Works & Numeric Comparison*/
286 /** pass_key - Shall be 0 for BT_SSP_PAIRING_VARIANT_CONSENT &
287  * BT_SSP_PAIRING_PASSKEY_ENTRY */
288 /* TODO: Passkey request callback shall not be needed for devices with display
289  * capability. We still need support this in the stack for completeness */
290 typedef void (*ssp_request_callback)(bt_bdaddr_t *remote_bd_addr,
291  bt_bdname_t *bd_name,
292  uint32_t cod,
293  bt_ssp_variant_t pairing_variant,
294  uint32_t pass_key);
295 
296 /** Bluetooth Bond state changed callback */
297 /* Invoked in response to create_bond, cancel_bond or remove_bond */
299  bt_bdaddr_t *remote_bd_addr,
300  bt_bond_state_t state);
301 
302 /** Bluetooth ACL connection state changed callback */
303 typedef void (*acl_state_changed_callback)(bt_status_t status, bt_bdaddr_t *remote_bd_addr,
304  bt_acl_state_t state);
305 
306 typedef enum {
310 
311 /** Thread Associate/Disassociate JVM Callback */
312 /* Callback that is invoked by the callback thread to allow upper layer to attach/detach to/from
313  * the JVM */
315 
316 /** Bluetooth Test Mode Callback */
317 /* Receive any HCI event from controller. Must be in DUT Mode for this callback to be received */
318 typedef void (*dut_mode_recv_callback)(uint16_t opcode, uint8_t *buf, uint8_t len);
319 
320 /* LE Test mode callbacks
321 * This callback shall be invoked whenever the le_tx_test, le_rx_test or le_test_end is invoked
322 * The num_packets is valid only for le_test_end command */
323 typedef void (*le_test_mode_callback)(bt_status_t status, uint16_t num_packets);
324 /** TODO: Add callbacks for Link Up/Down and other generic
325  * notifications/callbacks */
326 
327 /** Bluetooth DM callback structure. */
328 typedef struct {
329  /** set to sizeof(bt_callbacks_t) */
330  size_t size;
344 
345 /** NOTE: By default, no profiles are initialized at the time of init/enable.
346  * Whenever the application invokes the 'init' API of a profile, then one of
347  * the following shall occur:
348  *
349  * 1.) If Bluetooth is not enabled, then the Bluetooth core shall mark the
350  * profile as enabled. Subsequently, when the application invokes the
351  * Bluetooth 'enable', as part of the enable sequence the profile that were
352  * marked shall be enabled by calling appropriate stack APIs. The
353  * 'adapter_properties_cb' shall return the list of UUIDs of the
354  * enabled profiles.
355  *
356  * 2.) If Bluetooth is enabled, then the Bluetooth core shall invoke the stack
357  * profile API to initialize the profile and trigger a
358  * 'adapter_properties_cb' with the current list of UUIDs including the
359  * newly added profile's UUID.
360  *
361  * The reverse shall occur whenever the profile 'cleanup' APIs are invoked
362  */
363 
364 /** Represents the standard Bluetooth DM interface. */
365 typedef struct {
366  /** set to sizeof(bt_interface_t) */
367  size_t size;
368  /**
369  * Opens the interface and provides the callback routines
370  * to the implemenation of this interface.
371  */
372  int (*init)(bt_callbacks_t* callbacks );
373 
374  /** Enable Bluetooth. */
375  int (*enable)(void);
376 
377  /** Disable Bluetooth. */
378  int (*disable)(void);
379 
380  /** Closes the interface. */
381  void (*cleanup)(void);
382 
383  /** Get all Bluetooth Adapter properties at init */
384  int (*get_adapter_properties)(void);
385 
386  /** Get Bluetooth Adapter property of 'type' */
387  int (*get_adapter_property)(bt_property_type_t type);
388 
389  /** Set Bluetooth Adapter property of 'type' */
390  /* Based on the type, val shall be one of
391  * bt_bdaddr_t or bt_bdname_t or bt_scanmode_t etc
392  */
393  int (*set_adapter_property)(const bt_property_t *property);
394 
395  /** Get all Remote Device properties */
396  int (*get_remote_device_properties)(bt_bdaddr_t *remote_addr);
397 
398  /** Get Remote Device property of 'type' */
399  int (*get_remote_device_property)(bt_bdaddr_t *remote_addr,
400  bt_property_type_t type);
401 
402  /** Set Remote Device property of 'type' */
403  int (*set_remote_device_property)(bt_bdaddr_t *remote_addr,
404  const bt_property_t *property);
405 
406  /** Get Remote Device's service record for the given UUID */
407  int (*get_remote_service_record)(bt_bdaddr_t *remote_addr,
408  bt_uuid_t *uuid);
409 
410  /** Start SDP to get remote services */
411  int (*get_remote_services)(bt_bdaddr_t *remote_addr);
412 
413  /** Start Discovery */
414  int (*start_discovery)(void);
415 
416  /** Cancel Discovery */
417  int (*cancel_discovery)(void);
418 
419  /** Create Bluetooth Bonding */
420  int (*create_bond)(const bt_bdaddr_t *bd_addr);
421 
422  /** Remove Bond */
423  int (*remove_bond)(const bt_bdaddr_t *bd_addr);
424 
425  /** Cancel Bond */
426  int (*cancel_bond)(const bt_bdaddr_t *bd_addr);
427 
428  /** BT Legacy PinKey Reply */
429  /** If accept==FALSE, then pin_len and pin_code shall be 0x0 */
430  int (*pin_reply)(const bt_bdaddr_t *bd_addr, uint8_t accept,
431  uint8_t pin_len, bt_pin_code_t *pin_code);
432 
433  /** BT SSP Reply - Just Works, Numeric Comparison and Passkey
434  * passkey shall be zero for BT_SSP_VARIANT_PASSKEY_COMPARISON &
435  * BT_SSP_VARIANT_CONSENT
436  * For BT_SSP_VARIANT_PASSKEY_ENTRY, if accept==FALSE, then passkey
437  * shall be zero */
438  int (*ssp_reply)(const bt_bdaddr_t *bd_addr, bt_ssp_variant_t variant,
439  uint8_t accept, uint32_t passkey);
440 
441  /** Get Bluetooth profile interface */
442  const void* (*get_profile_interface) (const char *profile_id);
443 
444  /** Bluetooth Test Mode APIs - Bluetooth must be enabled for these APIs */
445  /* Configure DUT Mode - Use this mode to enter/exit DUT mode */
446  int (*dut_mode_configure)(uint8_t enable);
447 
448  /* Send any test HCI (vendor-specific) command to the controller. Must be in DUT Mode */
449  int (*dut_mode_send)(uint16_t opcode, uint8_t *buf, uint8_t len);
450  /** BLE Test Mode APIs */
451  /* opcode MUST be one of: LE_Receiver_Test, LE_Transmitter_Test, LE_Test_End */
452  int (*le_test_mode)(uint16_t opcode, uint8_t *buf, uint8_t len);
453 
454  /* enable or disable bluetooth HCI snoop log */
455  int (*config_hci_snoop_log)(uint8_t enable);
457 
458 /** TODO: Need to add APIs for Service Discovery, Service authorization and
459  * connection management. Also need to add APIs for configuring
460  * properties of remote bonded devices such as name, UUID etc. */
461 
462 typedef struct {
463  struct hw_device_t common;
464  const bt_interface_t* (*get_bluetooth_interface)();
466 
468 __END_DECLS
469 
470 #endif /* ANDROID_INCLUDE_BLUETOOTH_H */