MT2523 API Reference  LinkIt SDK v4
Classic Bluetooth

This section describes the Generic Access Profile (GAP) APIs for Bluetooth with Enhanced Data Rate (EDR). More...

Overview

This section describes the Generic Access Profile (GAP) APIs for Bluetooth with Enhanced Data Rate (EDR).

The GAP defines the generic procedures related to discovery of Bluetooth devices and link management aspects of connecting to Bluetooth devices.

Terms and Acronyms

Terms Details
GAP Generic Access Profile. This profile defines the generic procedures related to discovery of Bluetooth devices and link management aspects of connecting to Bluetooth devices. It also defines procedures related to use of different security levels.
RSSI Received Signal Strength Indication. For more information, please refer to Wikipedia.
SSP Secure Simple Pairing. Simplifies the pairing process and improves Bluetooth security.
IO Capability Input/Output Capability. It is used in pairing feature exchange process to determine which pairing method to use.
MITM Man-in-the-middle Protection. For more information, please refer to Wikipedia.
COD Class of Device, indicating the type of device.
EIR Extended Inquiry Response data. It is sent during the inquiry response state. It can contain device name, transmit power level, service class UUIDs and more.
HCI Host Controller Interface. For more information, please refer to Wikipedia.

How to use this module

Functions

bt_status_t bt_gap_set_scan_mode (bt_gap_scan_mode_t mode)
 This function sets the accessible mode. More...
 
bt_status_t bt_gap_inquiry (uint8_t duration, uint8_t max_count)
 This function inquires the search for nearby devices. More...
 
bt_status_t bt_gap_cancel_inquiry (void)
 This function stops the inquiry. More...
 
bt_status_t bt_gap_disconnect (bt_gap_connection_handle_t handle)
 This function disconnects the special link. More...
 
bt_status_t bt_gap_set_role (bt_gap_connection_handle_t handle, bt_role_t role)
 This function changes the device's role type. More...
 
bt_status_t bt_gap_get_role (bt_gap_connection_handle_t handle)
 This function gets the device's role type. More...
 
bt_status_t bt_gap_read_remote_name (const bt_bd_addr_t *address)
 This function gets the device's name, no need to be connected to the device. More...
 
bt_status_t bt_gap_cancel_name_request (const bt_bd_addr_t *address)
 This function cancels the request of bt_gap_read_remote_name(). More...
 
bt_status_t bt_gap_enter_test_mode (void)
 This function sets the device into a test mode. More...
 
bt_status_t bt_gap_set_extended_inquiry_response (uint8_t *eir_data, uint32_t data_length)
 This function sets the EIR data. More...
 
bt_status_t bt_gap_write_inquiry_tx (int8_t tx_power)
 This function writes the inquiry transmit power. More...
 
bt_status_t bt_gap_read_inquiry_response_tx (void)
 This function reads the inquiry response transmit power. More...
 
bt_status_t bt_gap_write_page_scan_activity (uint16_t interval, uint16_t window)
 This function writes the values for the interval and the window of page scanning. More...
 
bt_status_t bt_gap_write_inquiry_scan_activity (uint16_t interval, uint16_t window)
 This function writes values for the interval and the window of inquiry scanning. More...
 
const bt_bd_addr_tbt_gap_get_remote_address (bt_gap_connection_handle_t handle)
 This function gets the address of a connected device. More...
 
bt_status_t bt_gap_read_rssi (bt_gap_connection_handle_t handle)
 This function reads the RSSI of the connected device. More...
 
const bt_gap_pin_code_information_tbt_gap_get_pin_code (void)
 This is a user defined callback to get the pin code and pass it to the GAP process. More...
 
bt_status_t bt_gap_reply_io_capability_request (bt_gap_oob_data_presented_t oob_present, bt_gap_security_auth_request_t auth_request)
 This function sends a reply to the BT_GAP_IO_CAPABILITY_REQ_IND event with Out-of-band data presented and security authentication request. More...
 
bt_status_t bt_gap_reject_io_capability_request (void)
 This function rejects the BT_GAP_IO_CAPABILITY_REQ_IND event and terminates the bonding. More...
 
bt_status_t bt_gap_reply_passkey_request (const uint32_t *passkey)
 This function is a reply to the BT_GAP_USER_REPLY_PASSKEY_IND event. More...
 
bt_status_t bt_gap_reply_user_confirm_request (bool accept)
 This function is a reply to the BT_GAP_USER_CONFIRM_REQ_IND event. More...
 
void bt_gap_get_link_key (bt_gap_link_key_notification_ind_t *key_information)
 This is a user defined callback to get the link key and pass it to the GAP process. More...
 
const bt_gap_config_tbt_gap_get_local_configuration (void)
 This is a user defined callback to get the configuration parameters for the GAP initialization process. More...
 
bt_status_t bt_gap_set_default_sniff_parameters (const bt_gap_default_sniff_params_t *sniff_params)
 This function sets the default sniff parameters. More...
 
bt_status_t bt_gap_set_default_sniff_subrating_parameters (const bt_gap_default_sniff_subrating_params_t *sniff_subrating_params)
 This function sets the default subrating_parameters. More...
 

Modules

 Define
 Define Classic Bluetooth GAP data types and values.
 
 Struct
 Define Classic Bluetooth GAP structures for GAP APIs and events.
 

Function Documentation

bt_status_t bt_gap_cancel_inquiry ( void  )

This function stops the inquiry.

Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_cancel_name_request ( const bt_bd_addr_t address)

This function cancels the request of bt_gap_read_remote_name().

Parameters
[in]addressis the address of the remote device.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_disconnect ( bt_gap_connection_handle_t  handle)

This function disconnects the special link.

Parameters
[in]handleis the link handle to be disconnected.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory. BT_STATUS_CONNECTION_NOT_FOUND, the operation has failed, the link does not exist.
bt_status_t bt_gap_enter_test_mode ( void  )

This function sets the device into a test mode.

Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
void bt_gap_get_link_key ( bt_gap_link_key_notification_ind_t key_information)

This is a user defined callback to get the link key and pass it to the GAP process.

Parameters
[in,out]key_informationprovide the key and key_type for a given address.
Returns
None.
const bt_gap_config_t* bt_gap_get_local_configuration ( void  )

This is a user defined callback to get the configuration parameters for the GAP initialization process.

Returns
the configuration information supplied by user.
const bt_gap_pin_code_information_t* bt_gap_get_pin_code ( void  )

This is a user defined callback to get the pin code and pass it to the GAP process.

Returns
A pointer to the pin information.
const bt_bd_addr_t* bt_gap_get_remote_address ( bt_gap_connection_handle_t  handle)

This function gets the address of a connected device.

Parameters
[in]handleis the connection handle.
Returns
A pointer to the address, if the operation completed successfully. NULL, if it failed.
bt_status_t bt_gap_get_role ( bt_gap_connection_handle_t  handle)

This function gets the device's role type.

The BT_GAP_GET_ROLE_CNF event is received when finished.

Parameters
[in]handleis the link handle.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_inquiry ( uint8_t  duration,
uint8_t  max_count 
)

This function inquires the search for nearby devices.

The BT_GAP_INQUIRY_IND event is received once a new device is found.

Parameters
[in]durationis the maximum time of the inquiry. The inquiry stops after the timeout. The range is from 0x01 to 0x30. Time = N * 1.28sec.
[in]max_countis the maximum device count of the inquiry, stops the inquiry, if the number of searched devices reaches the max_count. The range is from 0x00 to 0xFF, 0 - unlimited number of responses.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_read_inquiry_response_tx ( void  )

This function reads the inquiry response transmit power.

The BT_GAP_READ_INQUIRY_RESPONSE_TX_CNF event is received once the operation is complete.

Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_read_remote_name ( const bt_bd_addr_t address)

This function gets the device's name, no need to be connected to the device.

The BT_GAP_READ_REMOTE_NAME_COMPLETE_IND event is received once the operation is complete.

Parameters
[in]addressis the address of the remote device.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_read_rssi ( bt_gap_connection_handle_t  handle)

This function reads the RSSI of the connected device.

BT_GAP_READ_RSSI_CNF event is received once the operation is complete.

Parameters
[in]handleis the link handle.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_reject_io_capability_request ( void  )

This function rejects the BT_GAP_IO_CAPABILITY_REQ_IND event and terminates the bonding.

Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has timed out. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_reply_io_capability_request ( bt_gap_oob_data_presented_t  oob_present,
bt_gap_security_auth_request_t  auth_request 
)

This function sends a reply to the BT_GAP_IO_CAPABILITY_REQ_IND event with Out-of-band data presented and security authentication request.

Parameters
[in]oob_presentis the Out-of-band data presented.
[in]auth_requestis the security authentication request.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has timed out. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_reply_passkey_request ( const uint32_t *  passkey)

This function is a reply to the BT_GAP_USER_REPLY_PASSKEY_IND event.

Parameters
[in]passkeyis a pointer to the user's passkey. If it is NULL, the reply is rejected.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has timed out. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_reply_user_confirm_request ( bool  accept)

This function is a reply to the BT_GAP_USER_CONFIRM_REQ_IND event.

Parameters
[in]acceptdefines whether the pairing is accepted.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has timed out. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_set_default_sniff_parameters ( const bt_gap_default_sniff_params_t sniff_params)

This function sets the default sniff parameters.

The default settings remain effective till the system reboot.

Parameters
[in]sniff_paramsis the default sniff parameters.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated.
bt_status_t bt_gap_set_default_sniff_subrating_parameters ( const bt_gap_default_sniff_subrating_params_t sniff_subrating_params)

This function sets the default subrating_parameters.

The default settings remain effective till the system reboot.

Parameters
[in]sniff_subrating_paramsis the default sniff subrating parameters.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated.
bt_status_t bt_gap_set_extended_inquiry_response ( uint8_t *  eir_data,
uint32_t  data_length 
)

This function sets the EIR data.

Parameters
[in]eir_datais the content of EIR data.
[in]data_lengthis the size of the EIR data, the maximum length is 240.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_set_role ( bt_gap_connection_handle_t  handle,
bt_role_t  role 
)

This function changes the device's role type.

The BT_GAP_ROLE_CHANGED_IND event is received when the role changed.

Parameters
[in]handleis the link handle to change.
[in]roleis the role to change.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_set_scan_mode ( bt_gap_scan_mode_t  mode)

This function sets the accessible mode.

Parameters
[in]modeis the accessing mode.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_write_inquiry_scan_activity ( uint16_t  interval,
uint16_t  window 
)

This function writes values for the interval and the window of inquiry scanning.

The BT_GAP_WRITING_INQUIRY_SCAN_CNF event will be received when finished.

Parameters
[in]intervalis the inquiry scan interval, default value is 0x1000, the range is from 0x12 to 0x1000. Time = N * 0.626 ms.
[in]windowis the inquiry scan window, it shall be less than or equal to interval, default value is 0x0012, the range is from 0x12 to 0x1000. Time = N * 0.626 ms.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_write_inquiry_tx ( int8_t  tx_power)

This function writes the inquiry transmit power.

Parameters
[in]tx_poweris the transmit power, the range is from -70 to 20.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.
bt_status_t bt_gap_write_page_scan_activity ( uint16_t  interval,
uint16_t  window 
)

This function writes the values for the interval and the window of page scanning.

The BT_GAP_WRITING_PAGE_SCAN_CNF event is received once the operation is complete.

Parameters
[in]intervalis the page scan interval, default value is 0x0800, the range is from 0x12 to 0x1000. Time = N * 0.626 ms.
[in]windowis the page scan window, it shall be less than or equal to interval, default value is 0x0012, the range is from 0x12 to 0x1000. Time = N * 0.626 ms.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, an error occurred, the operation has terminated. BT_STATUS_OUT_OF_MEMORY, the operation has failed, out of memory.