include/hardware/bt_gatt_client.h

   1 /*
   2  * Copyright (C) 2013 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
  18 #ifndef ANDROID_INCLUDE_BT_GATT_CLIENT_H
  19 #define ANDROID_INCLUDE_BT_GATT_CLIENT_H
  20
  21 #include <stdint.h>
  22 #include "bt_gatt_types.h"
  23
  24 __BEGIN_DECLS
  25
  26 /**
  27  * Buffer sizes for maximum attribute length and maximum read/write
  28  * operation buffer size.
  29  */
  30 #define BTGATT_MAX_ATTR_LEN 600
  31
  32 /** Buffer type for unformatted reads/writes */
  33 typedef struct
  34 {
  35     uint8_t             value[BTGATT_MAX_ATTR_LEN];
  36     uint16_t            len;
  37 } btgatt_unformatted_value_t;
  38
  39 /** Parameters for GATT read operations */
  40 typedef struct
  41 {
  42     btgatt_srvc_id_t    srvc_id;
  43     btgatt_gatt_id_t    char_id;
  44     btgatt_gatt_id_t    descr_id;
  45     btgatt_unformatted_value_t value;
  46     uint16_t            value_type;
  47     uint8_t             status;
  48 } btgatt_read_params_t;
  49
  50 /** Parameters for GATT write operations */
  51 typedef struct
  52 {
  53     btgatt_srvc_id_t    srvc_id;
  54     btgatt_gatt_id_t    char_id;
  55     btgatt_gatt_id_t    descr_id;
  56     uint8_t             status;
  57 } btgatt_write_params_t;
  58
  59 /** Attribute change notification parameters */
  60 typedef struct
  61 {
  62     uint8_t             value[BTGATT_MAX_ATTR_LEN];
  63     bt_bdaddr_t         bda;
  64     btgatt_srvc_id_t    srvc_id;
  65     btgatt_gatt_id_t    char_id;
  66     uint16_t            len;
  67     uint8_t             is_notify;
  68 } btgatt_notify_params_t;
  69
  70 typedef struct
  71 {
  72     bt_bdaddr_t        *bda1;
  73     bt_uuid_t          *uuid1;
  74     uint16_t            u1;
  75     uint16_t            u2;
  76     uint16_t            u3;
  77     uint16_t            u4;
  78     uint16_t            u5;
  79 } btgatt_test_params_t;
  80
  81 /** BT-GATT Client callback structure. */
  82
  83 /** Callback invoked in response to register_client */
  84 typedef void (*register_client_callback)(int status, int client_if,
  85                 bt_uuid_t *app_uuid);
  86
  87 /** Callback for scan results */
  88 typedef void (*scan_result_callback)(bt_bdaddr_t* bda, int rssi, uint8_t* adv_data);
  89
  90 /** GATT open callback invoked in response to open */
  91 typedef void (*connect_callback)(int conn_id, int status, int client_if, bt_bdaddr_t* bda);
  92
  93 /** Callback invoked in response to close */
  94 typedef void (*disconnect_callback)(int conn_id, int status,
  95                 int client_if, bt_bdaddr_t* bda);
  96
  97 /**
  98  * Invoked in response to search_service when the GATT service search
  99  * has been completed.
 100  */
 101 typedef void (*search_complete_callback)(int conn_id, int status);
 102
 103 /** Reports GATT services on a remote device */
 104 typedef void (*search_result_callback)( int conn_id, btgatt_srvc_id_t *srvc_id);
 105
 106 /** GATT characteristic enumeration result callback */
 107 typedef void (*get_characteristic_callback)(int conn_id, int status,
 108                 btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *char_id,
 109                 int char_prop);
 110
 111 /** GATT descriptor enumeration result callback */
 112 typedef void (*get_descriptor_callback)(int conn_id, int status,
 113                 btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *char_id,
 114                 btgatt_gatt_id_t *descr_id);
 115
 116 /** GATT included service enumeration result callback */
 117 typedef void (*get_included_service_callback)(int conn_id, int status,
 118                 btgatt_srvc_id_t *srvc_id, btgatt_srvc_id_t *incl_srvc_id);
 119
 120 /** Callback invoked in response to [de]register_for_notification */
 121 typedef void (*register_for_notification_callback)(int conn_id,
 122                 int registered, int status, btgatt_srvc_id_t *srvc_id,
 123                 btgatt_gatt_id_t *char_id);
 124
 125 /**
 126  * Remote device notification callback, invoked when a remote device sends
 127  * a notification or indication that a client has registered for.
 128  */
 129 typedef void (*notify_callback)(int conn_id, btgatt_notify_params_t *p_data);
 130
 131 /** Reports result of a GATT read operation */
 132 typedef void (*read_characteristic_callback)(int conn_id, int status,
 133                 btgatt_read_params_t *p_data);
 134
 135 /** GATT write characteristic operation callback */
 136 typedef void (*write_characteristic_callback)(int conn_id, int status,
 137                 btgatt_write_params_t *p_data);
 138
 139 /** GATT execute prepared write callback */
 140 typedef void (*execute_write_callback)(int conn_id, int status);
 141
 142 /** Callback invoked in response to read_descriptor */
 143 typedef void (*read_descriptor_callback)(int conn_id, int status,
 144                 btgatt_read_params_t *p_data);
 145
 146 /** Callback invoked in response to write_descriptor */
 147 typedef void (*write_descriptor_callback)(int conn_id, int status,
 148                 btgatt_write_params_t *p_data);
 149
 150 /** Callback triggered in response to read_remote_rssi */
 151 typedef void (*read_remote_rssi_callback)(int client_if, bt_bdaddr_t* bda,
 152                                           int rssi, int status);
 153
 154 /**
 155  * Callback indicating the status of a listen() operation
 156  */
 157 typedef void (*listen_callback)(int status, int server_if);
 158
 159 /** Callback invoked when the MTU for a given connection changes */
 160 typedef void (*configure_mtu_callback)(int conn_id, int status, int mtu);
 161
 162 /** Callback invoked when a scan filter configuration command has completed */
 163 typedef void (*scan_filter_cfg_callback)(int action, int client_if, int status, int filt_type,
 164                                          int avbl_space);
 165
 166 /** Callback invoked when scan param has been added, cleared, or deleted */
 167 typedef void (*scan_filter_param_callback)(int action, int client_if, int status,
 168                                          int avbl_space);
 169
 170 /** Callback invoked when a scan filter configuration command has completed */
 171 typedef void (*scan_filter_status_callback)(int enable, int client_if, int status);
 172
 173 /** Callback invoked when multi-adv enable operation has completed */
 174 typedef void (*multi_adv_enable_callback)(int client_if, int status);
 175
 176 /** Callback invoked when multi-adv param update operation has completed */
 177 typedef void (*multi_adv_update_callback)(int client_if, int status);
 178
 179 /** Callback invoked when multi-adv instance data set operation has completed */
 180 typedef void (*multi_adv_data_callback)(int client_if, int status);
 181
 182 /** Callback invoked when multi-adv disable operation has completed */
 183 typedef void (*multi_adv_disable_callback)(int client_if, int status);
 184
 185 /**
 186  * Callback notifying an application that a remote device connection is currently congested
 187  * and cannot receive any more data. An application should avoid sending more data until
 188  * a further callback is received indicating the congestion status has been cleared.
 189  */
 190 typedef void (*congestion_callback)(int conn_id, bool congested);
 191 /** Callback invoked when batchscan storage config operation has completed */
 192 typedef void (*batchscan_cfg_storage_callback)(int client_if, int status);
 193
 194 /** Callback invoked when batchscan enable / disable operation has completed */
 195 typedef void (*batchscan_enable_disable_callback)(int action, int client_if, int status);
 196
 197 /** Callback invoked when batchscan reports are obtained */
 198 typedef void (*batchscan_reports_callback)(int client_if, int status, int report_format,
 199                                            int num_records, int data_len, uint8_t* rep_data);
 200
 201 /** Callback invoked when batchscan storage threshold limit is crossed */
 202 typedef void (*batchscan_threshold_callback)(int client_if);
 203
 204 /** Track ADV VSE callback invoked when tracked device is found or lost */
 205 typedef void (*track_adv_event_callback)(int client_if, int filt_index, int addr_type,
 206                                              bt_bdaddr_t* bda, int adv_state);
 207
 208 typedef struct {
 209     register_client_callback            register_client_cb;
 210     scan_result_callback                scan_result_cb;
 211     connect_callback                    open_cb;
 212     disconnect_callback                 close_cb;
 213     search_complete_callback            search_complete_cb;
 214     search_result_callback              search_result_cb;
 215     get_characteristic_callback         get_characteristic_cb;
 216     get_descriptor_callback             get_descriptor_cb;
 217     get_included_service_callback       get_included_service_cb;
 218     register_for_notification_callback  register_for_notification_cb;
 219     notify_callback                     notify_cb;
 220     read_characteristic_callback        read_characteristic_cb;
 221     write_characteristic_callback       write_characteristic_cb;
 222     read_descriptor_callback            read_descriptor_cb;
 223     write_descriptor_callback           write_descriptor_cb;
 224     execute_write_callback              execute_write_cb;
 225     read_remote_rssi_callback           read_remote_rssi_cb;
 226     listen_callback                     listen_cb;
 227     configure_mtu_callback              configure_mtu_cb;
 228     scan_filter_cfg_callback            scan_filter_cfg_cb;
 229     scan_filter_param_callback          scan_filter_param_cb;
 230     scan_filter_status_callback         scan_filter_status_cb;
 231     multi_adv_enable_callback           multi_adv_enable_cb;
 232     multi_adv_update_callback           multi_adv_update_cb;
 233     multi_adv_data_callback             multi_adv_data_cb;
 234     multi_adv_disable_callback          multi_adv_disable_cb;
 235     congestion_callback                 congestion_cb;
 236     batchscan_cfg_storage_callback      batchscan_cfg_storage_cb;
 237     batchscan_enable_disable_callback   batchscan_enb_disable_cb;
 238     batchscan_reports_callback          batchscan_reports_cb;
 239     batchscan_threshold_callback        batchscan_threshold_cb;
 240     track_adv_event_callback            track_adv_event_cb;
 241 } btgatt_client_callbacks_t;
 242
 243 /** Represents the standard BT-GATT client interface. */
 244
 245 typedef struct {
 246     /** Registers a GATT client application with the stack */
 247     bt_status_t (*register_client)( bt_uuid_t *uuid );
 248
 249     /** Unregister a client application from the stack */
 250     bt_status_t (*unregister_client)(int client_if );
 251
 252     /** Start or stop LE device scanning */
 253     bt_status_t (*scan)( bool start );
 254
 255     /** Create a connection to a remote LE or dual-mode device */
 256     bt_status_t (*connect)( int client_if, const bt_bdaddr_t *bd_addr,
 257                          bool is_direct, int transport );
 258
 259     /** Disconnect a remote device or cancel a pending connection */
 260     bt_status_t (*disconnect)( int client_if, const bt_bdaddr_t *bd_addr,
 261                     int conn_id);
 262
 263     /** Start or stop advertisements to listen for incoming connections */
 264     bt_status_t (*listen)(int client_if, bool start);
 265
 266     /** Clear the attribute cache for a given device */
 267     bt_status_t (*refresh)( int client_if, const bt_bdaddr_t *bd_addr );
 268
 269     /**
 270      * Enumerate all GATT services on a connected device.
 271      * Optionally, the results can be filtered for a given UUID.
 272      */
 273     bt_status_t (*search_service)(int conn_id, bt_uuid_t *filter_uuid );
 274
 275     /**
 276      * Enumerate included services for a given service.
 277      * Set start_incl_srvc_id to NULL to get the first included service.
 278      */
 279     bt_status_t (*get_included_service)( int conn_id, btgatt_srvc_id_t *srvc_id,
 280                                          btgatt_srvc_id_t *start_incl_srvc_id);
 281
 282     /**
 283      * Enumerate characteristics for a given service.
 284      * Set start_char_id to NULL to get the first characteristic.
 285      */
 286     bt_status_t (*get_characteristic)( int conn_id,
 287                     btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *start_char_id);
 288
 289     /**
 290      * Enumerate descriptors for a given characteristic.
 291      * Set start_descr_id to NULL to get the first descriptor.
 292      */
 293     bt_status_t (*get_descriptor)( int conn_id,
 294                     btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *char_id,
 295                     btgatt_gatt_id_t *start_descr_id);
 296
 297     /** Read a characteristic on a remote device */
 298     bt_status_t (*read_characteristic)( int conn_id,
 299                     btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *char_id,
 300                     int auth_req );
 301
 302     /** Write a remote characteristic */
 303     bt_status_t (*write_characteristic)(int conn_id,
 304                     btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *char_id,
 305                     int write_type, int len, int auth_req,
 306                     char* p_value);
 307
 308     /** Read the descriptor for a given characteristic */
 309     bt_status_t (*read_descriptor)(int conn_id,
 310                     btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *char_id,
 311                     btgatt_gatt_id_t *descr_id, int auth_req);
 312
 313     /** Write a remote descriptor for a given characteristic */
 314     bt_status_t (*write_descriptor)( int conn_id,
 315                     btgatt_srvc_id_t *srvc_id, btgatt_gatt_id_t *char_id,
 316                     btgatt_gatt_id_t *descr_id, int write_type, int len,
 317                     int auth_req, char* p_value);
 318
 319     /** Execute a prepared write operation */
 320     bt_status_t (*execute_write)(int conn_id, int execute);
 321
 322     /**
 323      * Register to receive notifications or indications for a given
 324      * characteristic
 325      */
 326     bt_status_t (*register_for_notification)( int client_if,
 327                     const bt_bdaddr_t *bd_addr, btgatt_srvc_id_t *srvc_id,
 328                     btgatt_gatt_id_t *char_id);
 329
 330     /** Deregister a previous request for notifications/indications */
 331     bt_status_t (*deregister_for_notification)( int client_if,
 332                     const bt_bdaddr_t *bd_addr, btgatt_srvc_id_t *srvc_id,
 333                     btgatt_gatt_id_t *char_id);
 334
 335     /** Request RSSI for a given remote device */
 336     bt_status_t (*read_remote_rssi)( int client_if, const bt_bdaddr_t *bd_addr);
 337
 338     /** Setup scan filter params */
 339     bt_status_t (*scan_filter_param_setup)(int client_if, int action, int filt_index, int feat_seln,
 340                                       int list_logic_type, int filt_logic_type, int rssi_high_thres,
 341                                       int rssi_low_thres, int dely_mode, int found_timeout,
 342                                       int lost_timeout, int found_timeout_cnt);
 343
 344
 345     /** Configure a scan filter condition  */
 346     bt_status_t (*scan_filter_add_remove)(int client_if, int action, int filt_type,
 347                                    int filt_index, int company_id,
 348                                    int company_id_mask, const bt_uuid_t *p_uuid,
 349                                    const bt_uuid_t *p_uuid_mask, const bt_bdaddr_t *bd_addr,
 350                                    char addr_type, int data_len, char* p_data, int mask_len,
 351                                    char* p_mask);
 352
 353     /** Clear all scan filter conditions for specific filter index*/
 354     bt_status_t (*scan_filter_clear)(int client_if, int filt_index);
 355
 356     /** Enable / disable scan filter feature*/
 357     bt_status_t (*scan_filter_enable)(int client_if, bool enable);
 358
 359     /** Determine the type of the remote device (LE, BR/EDR, Dual-mode) */
 360     int (*get_device_type)( const bt_bdaddr_t *bd_addr );
 361
 362     /** Set the advertising data or scan response data */
 363     bt_status_t (*set_adv_data)(int client_if, bool set_scan_rsp, bool include_name,
 364                     bool include_txpower, int min_interval, int max_interval, int appearance,
 365                     uint16_t manufacturer_len, char* manufacturer_data,
 366                     uint16_t service_data_len, char* service_data,
 367                     uint16_t service_uuid_len, char* service_uuid);
 368
 369     /** Configure the MTU for a given connection */
 370     bt_status_t (*configure_mtu)(int conn_id, int mtu);
 371
 372     /** Request a connection parameter update */
 373     bt_status_t (*conn_parameter_update)(const bt_bdaddr_t *bd_addr, int min_interval,
 374                     int max_interval, int latency, int timeout);
 375
 376     /** Sets the LE scan interval and window in units of N*0.625 msec */
 377     bt_status_t (*set_scan_parameters)(int scan_interval, int scan_window);
 378
 379     /* Setup the parameters as per spec, user manual specified values and enable multi ADV */
 380     bt_status_t (*multi_adv_enable)(int client_if, int min_interval,int max_interval,int adv_type,
 381                  int chnl_map, int tx_power, int timeout_s);
 382
 383     /* Update the parameters as per spec, user manual specified values and restart multi ADV */
 384     bt_status_t (*multi_adv_update)(int client_if, int min_interval,int max_interval,int adv_type,
 385                  int chnl_map, int tx_power, int timeout_s);
 386
 387     /* Setup the data for the specified instance */
 388     bt_status_t (*multi_adv_set_inst_data)(int client_if, bool set_scan_rsp, bool include_name,
 389                     bool incl_txpower, int appearance, int manufacturer_len,
 390                     char* manufacturer_data, int service_data_len,
 391                     char* service_data, int service_uuid_len, char* service_uuid);
 392
 393     /* Disable the multi adv instance */
 394     bt_status_t (*multi_adv_disable)(int client_if);
 395
 396     /* Configure the batchscan storage */
 397     bt_status_t (*batchscan_cfg_storage)(int client_if, int batch_scan_full_max,
 398         int batch_scan_trunc_max, int batch_scan_notify_threshold);
 399
 400     /* Enable batchscan */
 401     bt_status_t (*batchscan_enb_batch_scan)(int client_if, int scan_mode,
 402         int scan_interval, int scan_window, int addr_type, int discard_rule);
 403
 404     /* Disable batchscan */
 405     bt_status_t (*batchscan_dis_batch_scan)(int client_if);
 406
 407     /* Read out batchscan reports */
 408     bt_status_t (*batchscan_read_reports)(int client_if, int scan_mode);
 409
 410     /** Test mode interface */
 411     bt_status_t (*test_command)( int command, btgatt_test_params_t* params);
 412
 413 } btgatt_client_interface_t;
 414
 415 __END_DECLS
 416
 417 #endif /* ANDROID_INCLUDE_BT_GATT_CLIENT_H */