stack/include/gap_api.h

   1 /******************************************************************************
   2  *
   3  *  Copyright (C) 2009-2013 Broadcom Corporation
   4  *
   5  *  Licensed under the Apache License, Version 2.0 (the "License");
   6  *  you may not use this file except in compliance with the License.
   7  *  You may obtain a copy of the License at:
   8  *
   9  *  http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *  Unless required by applicable law or agreed to in writing, software
  12  *  distributed under the License is distributed on an "AS IS" BASIS,
  13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *  See the License for the specific language governing permissions and
  15  *  limitations under the License.
  16  *
  17  ******************************************************************************/
  18
  19 #ifndef GAP_API_H
  20 #define GAP_API_H
  21
  22 #include "profiles_api.h"
  23 #include "btm_api.h"
  24 #include "l2c_api.h"
  25
  26 /*****************************************************************************
  27 **  Constants
  28 *****************************************************************************/
  29 /*** GAP Error and Status Codes ***/
  30 #define GAP_UNSUPPORTED     (GAP_ERR_GRP + 0x01)    /* Unsupported call */
  31 #define GAP_EOINQDB         (GAP_ERR_GRP + 0x02)    /* End of inquiry database marker */
  32 #define GAP_ERR_BUSY        (GAP_ERR_GRP + 0x03)    /* The requested function was busy */
  33 #define GAP_ERR_NO_CTRL_BLK (GAP_ERR_GRP + 0x04)    /* No control blocks available */
  34 #define GAP_ERR_STARTING_CMD (GAP_ERR_GRP + 0x05)   /* Error occurred while initiating the command */
  35 #define GAP_NO_BDADDR_REC   (GAP_ERR_GRP + 0x06)    /* No Inquiry DB record for BD_ADDR */
  36 #define GAP_ERR_ILL_MODE    (GAP_ERR_GRP + 0x07)    /* An illegal mode parameter was detected */
  37 #define GAP_ERR_ILL_INQ_TIME (GAP_ERR_GRP + 0x08)   /* An illegal time parameter was detected */
  38 #define GAP_ERR_ILL_PARM     (GAP_ERR_GRP + 0x09)   /* An illegal parameter was detected */
  39 #define GAP_ERR_REM_NAME    (GAP_ERR_GRP + 0x0a)    /* Error starting the remote device name request */
  40 #define GAP_CMD_INITIATED   (GAP_ERR_GRP + 0x0b)    /* The GAP command was started (result pending) */
  41 #define GAP_DEVICE_NOT_UP   (GAP_ERR_GRP + 0x0c)    /* The device was not up; the request was not executed */
  42 #define GAP_BAD_BD_ADDR     (GAP_ERR_GRP + 0x0d)    /* The bd addr passed in was not found or invalid */
  43
  44 #define GAP_ERR_BAD_HANDLE  (GAP_ERR_GRP + 0x0e)    /* Bad GAP handle                       */
  45 #define GAP_ERR_BUF_OFFSET  (GAP_ERR_GRP + 0x0f)    /* Buffer offset invalid                */
  46 #define GAP_ERR_BAD_STATE   (GAP_ERR_GRP + 0x10)    /* Connection is in invalid state       */
  47 #define GAP_NO_DATA_AVAIL   (GAP_ERR_GRP + 0x11)    /* No data available                    */
  48 #define GAP_ERR_CONGESTED   (GAP_ERR_GRP + 0x12)    /* BT stack is congested                */
  49 #define GAP_ERR_SECURITY    (GAP_ERR_GRP + 0x13)    /* Security failed                      */
  50
  51 #define GAP_ERR_PROCESSING  (GAP_ERR_GRP + 0x14)    /* General error processing BTM request */
  52 #define GAP_ERR_TIMEOUT     (GAP_ERR_GRP + 0x15)    /* Timeout occurred while processing cmd */
  53 #define GAP_EVT_CONN_OPENED         0x0100
  54 #define GAP_EVT_CONN_CLOSED         0x0101
  55 #define GAP_EVT_CONN_DATA_AVAIL     0x0102
  56 #define GAP_EVT_CONN_CONGESTED      0x0103
  57 #define GAP_EVT_CONN_UNCONGESTED    0x0104
  58 /* Values for 'chan_mode_mask' field */
  59 /* GAP_ConnOpen() - optional channels to negotiate */
  60 #define GAP_FCR_CHAN_OPT_BASIC      L2CAP_FCR_CHAN_OPT_BASIC
  61 #define GAP_FCR_CHAN_OPT_ERTM       L2CAP_FCR_CHAN_OPT_ERTM
  62 #define GAP_FCR_CHAN_OPT_STREAM     L2CAP_FCR_CHAN_OPT_STREAM
  63 /*** used in connection variables and functions ***/
  64 #define GAP_INVALID_HANDLE      0xFFFF
  65
  66 /* This is used to change the criteria for AMP  */
  67 #define GAP_PROTOCOL_ID         (UUID_PROTOCOL_UDP)
  68
  69
  70 #ifndef  GAP_PREFER_CONN_INT_MAX
  71 #define  GAP_PREFER_CONN_INT_MAX         BTM_BLE_CONN_INT_MIN
  72 #endif
  73
  74 #ifndef  GAP_PREFER_CONN_INT_MIN
  75 #define  GAP_PREFER_CONN_INT_MIN         BTM_BLE_CONN_INT_MIN
  76 #endif
  77
  78 #ifndef  GAP_PREFER_CONN_LATENCY
  79 #define  GAP_PREFER_CONN_LATENCY         0
  80 #endif
  81
  82 #ifndef  GAP_PREFER_CONN_SP_TOUT
  83 #define  GAP_PREFER_CONN_SP_TOUT         2000
  84 #endif
  85
  86 /*****************************************************************************
  87 **  Type Definitions
  88 *****************************************************************************/
  89 /*
  90 ** Callback function for connection services
  91 */
  92 typedef void (tGAP_CONN_CALLBACK) (UINT16 gap_handle, UINT16 event);
  93
  94 /*
  95 ** Define the callback function prototypes.  Parameters are specific
  96 ** to each event and are described below
  97 */
  98 typedef void (tGAP_CALLBACK) (UINT16 event, void *p_data);
  99
 100
 101 /* Definition of the GAP_FindAddrByName results structure */
 102 typedef struct
 103 {
 104     UINT16       status;
 105     BD_ADDR      bd_addr;
 106     tBTM_BD_NAME devname;
 107 } tGAP_FINDADDR_RESULTS;
 108
 109 typedef struct
 110 {
 111     UINT16      int_min;
 112     UINT16      int_max;
 113     UINT16      latency;
 114     UINT16      sp_tout;
 115 }tGAP_BLE_PREF_PARAM;
 116
 117 typedef union
 118 {
 119     tGAP_BLE_PREF_PARAM     conn_param;
 120     BD_ADDR                 reconn_bda;
 121     UINT16                  icon;
 122     UINT8                   *p_dev_name;
 123     UINT8                   addr_resolution;
 124
 125 }tGAP_BLE_ATTR_VALUE;
 126
 127 typedef void (tGAP_BLE_CMPL_CBACK)(BOOLEAN status, BD_ADDR addr, UINT16 length, char *p_name);
 128
 129
 130 /*****************************************************************************
 131 **  External Function Declarations
 132 *****************************************************************************/
 133
 134 /*** Functions for L2CAP connection interface ***/
 135
 136 /*******************************************************************************
 137 **
 138 ** Function         GAP_ConnOpen
 139 **
 140 ** Description      This function is called to open a generic L2CAP connection.
 141 **
 142 ** Returns          handle of the connection if successful, else GAP_INVALID_HANDLE
 143 **
 144 *******************************************************************************/
 145 extern UINT16 GAP_ConnOpen (char *p_serv_name, UINT8 service_id, BOOLEAN is_server,
 146                                     BD_ADDR p_rem_bda, UINT16 psm, tL2CAP_CFG_INFO *p_cfg,
 147                                     tL2CAP_ERTM_INFO *ertm_info,
 148                                     UINT16 security, UINT8 chan_mode_mask, tGAP_CONN_CALLBACK *p_cb);
 149
 150 /*******************************************************************************
 151 **
 152 ** Function         GAP_ConnClose
 153 **
 154 ** Description      This function is called to close a connection.
 155 **
 156 ** Returns          BT_PASS             - closed OK
 157 **                  GAP_ERR_BAD_HANDLE  - invalid handle
 158 **
 159 *******************************************************************************/
 160 extern UINT16 GAP_ConnClose (UINT16 gap_handle);
 161
 162 /*******************************************************************************
 163 **
 164 ** Function         GAP_ConnReadData
 165 **
 166 ** Description      GKI buffer unaware application will call this function
 167 **                  after receiving GAP_EVT_RXDATA event. A data copy is made
 168 **                  into the receive buffer parameter.
 169 **
 170 ** Returns          BT_PASS             - data read
 171 **                  GAP_ERR_BAD_HANDLE  - invalid handle
 172 **                  GAP_NO_DATA_AVAIL   - no data available
 173 **
 174 *******************************************************************************/
 175 extern UINT16 GAP_ConnReadData (UINT16 gap_handle, UINT8 *p_data,
 176                                         UINT16 max_len, UINT16 *p_len);
 177
 178 /*******************************************************************************
 179 **
 180 ** Function         GAP_GetRxQueueCnt
 181 **
 182 ** Description      This function return number of bytes on the rx queue.
 183 **
 184 ** Parameters:      handle     - Handle returned in the GAP_ConnOpen
 185 **                  p_rx_queue_count - Pointer to return queue count in.
 186 **
 187 **
 188 *******************************************************************************/
 189 extern int GAP_GetRxQueueCnt (UINT16 handle, UINT32 *p_rx_queue_count);
 190
 191 /*******************************************************************************
 192 **
 193 ** Function         GAP_ConnBTRead
 194 **
 195 ** Description      GKI buffer aware applications will call this function after
 196 **                  receiving an GAP_EVT_RXDATA event to process the incoming
 197 **                  data buffer.
 198 **
 199 ** Returns          BT_PASS             - data read
 200 **                  GAP_ERR_BAD_HANDLE  - invalid handle
 201 **                  GAP_NO_DATA_AVAIL   - no data available
 202 **
 203 *******************************************************************************/
 204 extern UINT16 GAP_ConnBTRead (UINT16 gap_handle, BT_HDR **pp_buf);
 205
 206 /*******************************************************************************
 207 **
 208 ** Function         GAP_ConnBTWrite
 209 **
 210 ** Description      GKI buffer aware applications can call this function to write data
 211 **                  by passing a pointer to the GKI buffer of data.
 212 **
 213 ** Returns          BT_PASS                 - data read
 214 **                  GAP_ERR_BAD_HANDLE      - invalid handle
 215 **                  GAP_ERR_BAD_STATE       - connection not established
 216 **                  GAP_INVALID_BUF_OFFSET  - buffer offset is invalid
 217 *******************************************************************************/
 218 extern UINT16 GAP_ConnBTWrite (UINT16 gap_handle, BT_HDR *p_buf);
 219
 220 /*******************************************************************************
 221 **
 222 ** Function         GAP_ConnWriteData
 223 **
 224 ** Description      GKI buffer unaware application will call this function
 225 **                  to send data to the connection. A data copy is made into a GKI
 226 **                  buffer.
 227 **
 228 ** Returns          BT_PASS                 - data read
 229 **                  GAP_ERR_BAD_HANDLE      - invalid handle
 230 **                  GAP_ERR_BAD_STATE       - connection not established
 231 **                  GAP_CONGESTION          - system is congested
 232 **
 233 *******************************************************************************/
 234 extern UINT16 GAP_ConnWriteData (UINT16 gap_handle, UINT8 *p_data,
 235                                          UINT16 max_len, UINT16 *p_len);
 236
 237 /*******************************************************************************
 238 **
 239 ** Function         GAP_ConnReconfig
 240 **
 241 ** Description      Applications can call this function to reconfigure the connection.
 242 **
 243 ** Returns          BT_PASS                 - config process started
 244 **                  GAP_ERR_BAD_HANDLE      - invalid handle
 245 **
 246 *******************************************************************************/
 247 extern UINT16 GAP_ConnReconfig (UINT16 gap_handle, tL2CAP_CFG_INFO *p_cfg);
 248
 249 /*******************************************************************************
 250 **
 251 ** Function         GAP_ConnSetIdleTimeout
 252 **
 253 ** Description      Higher layers call this function to set the idle timeout for
 254 **                  a connection, or for all future connections. The "idle timeout"
 255 **                  is the amount of time that a connection can remain up with
 256 **                  no L2CAP channels on it. A timeout of zero means that the
 257 **                  connection will be torn down immediately when the last channel
 258 **                  is removed. A timeout of 0xFFFF means no timeout. Values are
 259 **                  in seconds.
 260 **
 261 ** Returns          BT_PASS                 - config process started
 262 **                  GAP_ERR_BAD_HANDLE      - invalid handle
 263 **
 264 *******************************************************************************/
 265 extern UINT16 GAP_ConnSetIdleTimeout (UINT16 gap_handle, UINT16 timeout);
 266
 267 /*******************************************************************************
 268 **
 269 ** Function         GAP_ConnGetRemoteAddr
 270 **
 271 ** Description      This function is called to get the remote BD address
 272 **                  of a connection.
 273 **
 274 ** Returns          BT_PASS             - closed OK
 275 **                  GAP_ERR_BAD_HANDLE  - invalid handle
 276 **
 277 *******************************************************************************/
 278 extern UINT8 *GAP_ConnGetRemoteAddr (UINT16 gap_handle);
 279
 280 /*******************************************************************************
 281 **
 282 ** Function         GAP_ConnGetRemMtuSize
 283 **
 284 ** Description      Returns the remote device's MTU size.
 285 **
 286 ** Returns          UINT16 - maximum size buffer that can be transmitted to the peer
 287 **
 288 *******************************************************************************/
 289 extern UINT16 GAP_ConnGetRemMtuSize (UINT16 gap_handle);
 290
 291 /*******************************************************************************
 292 **
 293 ** Function         GAP_ConnGetL2CAPCid
 294 **
 295 ** Description      Returns the L2CAP channel id
 296 **
 297 ** Parameters:      handle      - Handle of the connection
 298 **
 299 ** Returns          UINT16      - The L2CAP channel id
 300 **                  0, if error
 301 **
 302 *******************************************************************************/
 303 extern UINT16 GAP_ConnGetL2CAPCid (UINT16 gap_handle);
 304
 305 /*******************************************************************************
 306 **
 307 ** Function         GAP_SetTraceLevel
 308 **
 309 ** Description      This function sets the trace level for GAP.  If called with
 310 **                  a value of 0xFF, it simply returns the current trace level.
 311 **
 312 ** Returns          The new or current trace level
 313 **
 314 *******************************************************************************/
 315 extern UINT8 GAP_SetTraceLevel (UINT8 new_level);
 316
 317 /*******************************************************************************
 318 **
 319 ** Function         GAP_Init
 320 **
 321 ** Description      Initializes the control blocks used by GAP.
 322 **                  This routine should not be called except once per
 323 **                      stack invocation.
 324 **
 325 ** Returns          Nothing
 326 **
 327 *******************************************************************************/
 328 extern void GAP_Init(void);
 329
 330 #if (BLE_INCLUDED == TRUE)
 331 /*******************************************************************************
 332 **
 333 ** Function         GAP_BleAttrDBUpdate
 334 **
 335 ** Description      update GAP local BLE attribute database.
 336 **
 337 ** Returns          Nothing
 338 **
 339 *******************************************************************************/
 340 extern void GAP_BleAttrDBUpdate(UINT16 attr_uuid, tGAP_BLE_ATTR_VALUE *p_value);
 341
 342
 343 /*******************************************************************************
 344 **
 345 ** Function         GAP_BleReadPeerPrefConnParams
 346 **
 347 ** Description      Start a process to read a connected peripheral's preferred
 348 **                  connection parameters
 349 **
 350 ** Returns          TRUE if read started, else FALSE if GAP is busy
 351 **
 352 *******************************************************************************/
 353 extern BOOLEAN GAP_BleReadPeerPrefConnParams (BD_ADDR peer_bda);
 354
 355 /*******************************************************************************
 356 **
 357 ** Function         GAP_BleReadPeerDevName
 358 **
 359 ** Description      Start a process to read a connected peripheral's device name.
 360 **
 361 ** Returns          TRUE if request accepted
 362 **
 363 *******************************************************************************/
 364 extern BOOLEAN GAP_BleReadPeerDevName (BD_ADDR peer_bda, tGAP_BLE_CMPL_CBACK *p_cback);
 365
 366
 367 /*******************************************************************************
 368 **
 369 ** Function         GAP_BleReadPeerAddressResolutionCap
 370 **
 371 ** Description      Start a process to read peer address resolution capability
 372 **
 373 ** Returns          TRUE if request accepted
 374 **
 375 *******************************************************************************/
 376 extern BOOLEAN GAP_BleReadPeerAddressResolutionCap (BD_ADDR peer_bda,
 377                                                     tGAP_BLE_CMPL_CBACK *p_cback);
 378
 379 /*******************************************************************************
 380 **
 381 ** Function         GAP_BleCancelReadPeerDevName
 382 **
 383 ** Description      Cancel reading a peripheral's device name.
 384 **
 385 ** Returns          TRUE if request accepted
 386 **
 387 *******************************************************************************/
 388 extern BOOLEAN GAP_BleCancelReadPeerDevName (BD_ADDR peer_bda);
 389
 390
 391 #endif
 392
 393 #endif  /* GAP_API_H */