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