Functions
Functions
BLE » Generic Access Profile (GAP) » Generic Access Profile (GAP) Management
Collaboration diagram for Functions:

## Functions
void | ble_gap_pair_enable (bool enable)
| Decide whether to support the pair feature. More...
uint16_t | ble_gap_addr_set (ble_gap_bdaddr_t const *p_addr)
| Set the device identity address (public or random static). More...
uint16_t | ble_gap_addr_get (ble_gap_bdaddr_t *p_addr)
| Get the device identity address (public or random static). More...
uint16_t | ble_gap_tx_power_set (ble_gap_actv_role_t role, uint8_t index, int8_t txpwr_dbm)
| Set the tx power. More...
uint16_t | ble_gap_tx_power_get (ble_gap_actv_role_t role, uint8_t index, int8_t *txpwr_dbm)
| Get the tx power. More...
uint16_t | ble_gap_irk_set (ble_gap_sec_key_t *p_irk)
| Set IRK used for resolvable random BD address generation (LSB first). More...
uint16_t | ble_gap_privacy_params_set (uint16_t renew_dur, bool enable_flag)
| Set privacy related parameters. More...
uint16_t | ble_gap_data_length_set (uint16_t sugg_max_tx_octet, uint16_t sugg_max_tx_time)
| Set suggested default LE data length. More...
uint16_t | ble_gap_l2cap_params_set (uint16_t max_mtu, uint16_t max_mps, uint8_t max_nb_lecb)
| Set L2CAP related parameters. More...
void | ble_gap_pref_phy_set (uint8_t tx_pref_phy, uint8_t rx_pref_phy)
| Set the preferred values for the transmitter PHY and receiver PHY. More...
uint16_t | ble_gap_path_compensation_set (int16_t tx_path_comp, int16_t rx_path_comp)
| Set the RF path gain or loss between the RF transceiver and the antenna contributed by intermediate components. More...
void | ble_gap_ppcp_present_set (bool present_flag)
| Set GAP Peripheral Preferred Connection Parameters present flag. More...
uint16_t | ble_gap_chnl_map_set (ble_gap_chnl_map_t *p_chnl_map)
| Set advertising channel map before advertising starting. More...
uint16_t | ble_gap_bond_devs_get (ble_gap_bond_dev_list_t *p_bond_list, uint8_t max_num)
| Get all bonded devices. More...
uint16_t | ble_gap_bond_devs_clear (void)
| Clear all bonded devices. More...
uint16_t | ble_gap_bond_dev_del (const ble_gap_bdaddr_t *p_peer_addr)
| Delete a bond device with the specified BD address. More...
uint16_t | ble_gap_whitelist_get (ble_gap_white_list_t *p_whitelist)
| Get the content of the whole white list. More...
uint16_t | ble_gap_whitelist_add (const ble_gap_white_list_t *p_whitelist)
| Add the devices into current white list. More...
uint16_t | ble_gap_whitelist_del (const ble_gap_white_list_t *p_whitelist)
| Delete the devices out of current white list. More...
uint16_t | ble_gap_whitelist_clear (void)
| Clear all the entries in the current white list. More...
uint16_t | ble_gap_per_adv_list_get (ble_gap_period_adv_list_t *p_pal_list)
| Get the content of the whole periodic advertising list. More...
uint16_t | ble_gap_per_adv_list_add (const ble_gap_period_adv_list_t *p_pal_list)
| Add the devices into current periodic advertising list. More...
uint16_t | ble_gap_per_adv_list_del (const ble_gap_period_adv_list_t *p_pal_list)
| Delete the devices out of periodic advertising list. More...
uint16_t | ble_gap_per_adv_list_clear (void)
| Clear all the entries in the current periodic advertising list. More...
uint16_t | ble_gap_rpa_list_get (ble_gap_ral_dev_list_t *p_rpa_list, uint8_t max_num)
| Get the RPA list info. More...
uint16_t | ble_gap_dev_info_get (ble_gap_dev_info_get_type_t type)
| Get the device information according to param type. More...
uint16_t | ble_gap_adv_param_set (uint8_t adv_idx, ble_gap_own_addr_t own_addr_type, ble_gap_adv_param_t *p_adv_param)
| Set parameters for advertising. More...
uint16_t | ble_gap_ext_adv_param_set (uint8_t adv_idx, ble_gap_own_addr_t own_addr_type, ble_gap_ext_adv_param_t *p_adv_param)
| Set extended parameters for advertising. More...
uint16_t | ble_gap_adv_data_set (uint8_t adv_idx, ble_gap_adv_data_type_t type, const uint8_t *p_data, uint16_t length)
| Set Advertising Data, Scan Response Data and Periodic Advertising Data. More...
uint16_t | ble_gap_update_adv_data (uint8_t adv_idx, ble_gap_adv_data_type_t type, const uint8_t *p_data, uint16_t length)
| Update Advertising Data, Scan Response Data and Periodic Advertising Data. More...
uint16_t | ble_gap_adv_start (uint8_t adv_idx, ble_gap_adv_time_param_t *p_timeout)
| Start advertising. More...
uint16_t | ble_gap_adv_stop (uint8_t adv_idx)
| Stop advertising. More...
uint16_t | ble_gap_scan_param_set (ble_gap_own_addr_t own_addr_type, ble_gap_scan_param_t *p_scan_param)
| Set parameters for scanning. More...
uint16_t | ble_gap_ext_scan_param_set (ble_gap_own_addr_t own_addr_type, ble_gap_ext_scan_param_t *p_scan_param)
| Set extended parameters for scanning. More...
uint16_t | ble_gap_scan_start (void)
| Start scanning. More...
uint16_t | ble_gap_scan_stop (void)
| Stop scanning. More...
uint16_t | ble_gap_per_sync_param_set (uint8_t per_sync_idx, ble_gap_per_sync_param_t *p_per_sync_param)
| Set the parameters used for periodic sync. More...
uint16_t | ble_gap_per_sync_start (uint8_t per_sync_idx)
| Start to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. More...
uint16_t | ble_gap_per_sync_stop (uint8_t per_sync_idx)
| Stop periodic synchronization. More...
uint16_t | ble_gap_connect (ble_gap_own_addr_t own_addr_type, ble_gap_init_param_t *p_init_param)
| Start a legacy connection to a device. More...
uint16_t | ble_gap_ext_connect (ble_gap_own_addr_t own_addr_type, ble_gap_ext_init_param_t *p_init_param)
| Start an extended connection to a device. More...
uint16_t | ble_gap_connect_cancel (void)
| Cancel an initiated connection. More...
void | ble_gap_appearance_set (uint16_t appearance)
| Set GAP appearance value. More...
uint16_t | ble_gap_appearance_get (uint16_t *p_appearance)
| Get GAP appearance value. More...
uint16_t | ble_gap_ppcp_set (ble_gap_conn_param_t const *p_conn_params)
| Set GAP Peripheral Preferred Connection Parameters. More...
uint16_t | ble_gap_ppcp_get (ble_gap_conn_param_t *p_conn_params)
| Get GAP Peripheral Preferred Connection Parameters. More...
uint16_t | ble_gap_device_name_set (ble_gap_dev_name_write_perm_t write_perm, uint8_t const *p_dev_name, uint16_t length)
| Set GAP device name. More...
uint16_t | ble_gap_device_name_get (uint8_t *p_dev_name, uint16_t *p_length)
| Get GAP device name. More...
uint16_t | ble_gap_lepsm_register (ble_gap_lepsm_register_t *p_lepsm)
| Register a LE Protocol/Service Multiplexer. More...
uint16_t | ble_gap_lepsm_unregister (uint16_t le_psm)
| Unregister a LE Protocol/Service Multiplexer. More...
uint16_t | ble_gap_privacy_mode_set (ble_gap_bdaddr_t peer_addr, ble_gap_privacy_mode_t mode)
| Set privacy mode for peer device. More...
uint16_t | ble_gap_rslv_addr_read (ble_gap_rslv_addr_read_op_id_t op_code, ble_gap_bdaddr_t peer_iden_addr)
| Read peer or local resolvable address, this address generated by controller. More...
uint16_t | ble_gap_per_adv_report_ctrl (uint8_t per_sync_index, bool enable_flag)
| Control periodic advertising report. More...
uint16_t | ble_gap_connless_cte_trans_param_set (uint8_t per_adv_index, gap_connless_cte_trans_param_t *param)
| Set connectionless CTE transmit parameters. More...
uint16_t | ble_gap_connless_cte_trans_enable_set (uint8_t per_adv_index, bool enable_flag)
| Set connectionless CTE transmit enable. More...
uint16_t | ble_gap_connless_iq_sample_enable_set (uint8_t per_sync_index, bool enable_flag, ble_gap_connless_iq_sample_param_t *param)
| Set connectionless IQ sampling enable. More...
void | ble_gap_register_conless_iq_report_cb (void(*cb)(uint8_t per_sync_idx, const ble_gap_connless_iq_report_t *iq_report))
| Register connectionless iq report event callback. More...
uint16_t | ble_gap_set_gdx_ranging_param (uint32_t base_addr, uint8_t cte_len)
| Set ranging parameter. More...

## Detailed Description

## Function Documentation

## ◆ ble_gap_addr_get()

uint16_t ble_gap_addr_get | ( | ble_gap_bdaddr_t * | p_addr | ) |

Get the device identity address (public or random static).

Parameters

  [in] | p_addr | The pointer for the returned identity address.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_addr_set()

uint16_t ble_gap_addr_set | ( | ble_gap_bdaddr_t const * | p_addr | ) |

Set the device identity address (public or random static).

Parameters

  [in] | p_addr | Provided public or static random address. If addr_type = 0, it means public address, If addr_type = 1, it means static random address.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_adv_data_set()

uint16_t ble_gap_adv_data_set | ( | uint8_t | adv_idx,
|  | ble_gap_adv_data_type_t | type,
|  | const uint8_t * | p_data,
|  | uint16_t | length
| ) |  |

Set Advertising Data, Scan Response Data and Periodic Advertising Data.

See ENUM ble_gap_ad_type_t for ADV Type definitions. See ENUM ble_gap_adv_flags_t for ADV flag definitions.

Parameters

  [in] | adv_idx | Advertising index, range is 0 to 4.
  [in] | type | Data type.
  [in] | p_data | The data pointer.
  [in] | length | Data length.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_INVALID_ADV_DATA_TYPE | Invalid advertising data type supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  User should not add extra Flags AD type as the BLE Stack has added the Flags AD type already.

## ◆ ble_gap_adv_param_set()

uint16_t ble_gap_adv_param_set | ( | uint8_t | adv_idx,
|  | ble_gap_own_addr_t | own_addr_type,
|  | ble_gap_adv_param_t * | p_adv_param
| ) |  |

Set parameters for advertising.

Note that this function must be called prior to advertising started.

Parameters

  [in] | adv_idx | Advertising index, range is 0 to 4.
  [in] | own_addr_type | Own BD address source of the local device.
  [in] | p_adv_param | The advertising parameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  Discovery mode param contains Flags AD type, setting adv data should not set the Flags AD type.
  This API is for legacy advertsing (BT Core Spec version <= 4.2).

## ◆ ble_gap_adv_start()

uint16_t ble_gap_adv_start | ( | uint8_t | adv_idx,
|  | ble_gap_adv_time_param_t * | p_timeout
| ) |  |

Start advertising.

Parameters

  [in] | adv_idx | Advertising index, range is 0 to 4.
  [in] | p_timeout | Advertising timing parameter.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  If advertising mode is directed high duty cycle mode, duration should be set nonzero and not be greater than 1.28s.
  This API is asynchronous.
  If the field scan_req_ind_en in ble_gap_adv_param_t is TRUE passed in ble_gap_adv_param_set function, or if the GAP_ADV_PROP_SCAN_REQ_NTF_EN_BIT is set in ble_gap_adv_prop_t and passed in ble_gap_ext_adv_param_set function, BLE_GAPM_EVT_SCAN_REQUEST event will be triggered once a scan request has been received.
  BLE_GAPM_EVT_ADV_START event will be triggered once the operation has completed.

## ◆ ble_gap_adv_stop()

uint16_t ble_gap_adv_stop | ( | uint8_t | adv_idx | ) |

Stop advertising.

Parameters

  [in] | adv_idx | Advertising index, range is 0 to 4.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.

Note
  This API is asynchronous.
  event BLE_GAPM_EVT_ADV_STOP will be triggered once the operation has completed or advertising has been stopped.

## ◆ ble_gap_appearance_get()

uint16_t ble_gap_appearance_get | ( | uint16_t * | p_appearance | ) |

Get GAP appearance value.

Parameters

  [out] | p_appearance | The pointer to appearance value.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_appearance_set()

void ble_gap_appearance_set | ( | uint16_t | appearance | ) |

Set GAP appearance value.

Parameters

  [in] | appearance | Appearance value.

## ◆ ble_gap_bond_dev_del()

uint16_t ble_gap_bond_dev_del | ( | const ble_gap_bdaddr_t * | p_peer_addr | ) |

Delete a bond device with the specified BD address.

Parameters

  [in] | p_peer_addr | Pointer to the BD addrss.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_SDK_INTERNAL | SDK internal error.
  SDK_ERR_NVDS_NOT_INIT | NVDS is not initiated.
  SDK_ERR_LIST_ITEM_NOT_FOUND | Item not found in list.
  SDK_ERR_LIST_FULL | List is full.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_bond_devs_clear()

uint16_t ble_gap_bond_devs_clear | ( | void |  | ) |

Clear all bonded devices.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_SDK_INTERNAL | SDK internal error.
  SDK_ERR_NVDS_NOT_INIT | NVDS is not initiated.
  SDK_ERR_LIST_ITEM_NOT_FOUND | Item not found in list.
  SDK_ERR_LIST_FULL | List is full.

## ◆ ble_gap_bond_devs_get()

uint16_t ble_gap_bond_devs_get | ( | ble_gap_bond_dev_list_t * | p_bond_list,
|  | uint8_t | max_num
| ) |  |

Get all bonded devices.

Parameters

  [in] | p_bond_list | Pointer to the bond list.
  [in] | max_num | max number of bond devices can be gotten.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_SDK_INTERNAL | SDK internal error.
  SDK_ERR_NVDS_NOT_INIT | NVDS is not initiated.
  SDK_ERR_LIST_ITEM_NOT_FOUND | Item not found in list.
  SDK_ERR_LIST_FULL | List is full.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_chnl_map_set()

uint16_t ble_gap_chnl_map_set | ( | ble_gap_chnl_map_t * | p_chnl_map | ) |

Set advertising channel map before advertising starting.

Note
  This API is asynchronous.
  Once the operation has completed, the event BLE_GAP_OPCODE_CHNL_MAP_SET will be called.

Parameters

  [in] | p_chnl_map | Bitmask of LE channel map. See enum ble_gap_chnl_map_t for BT Core Spec version <= 4.2.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_connect()

uint16_t ble_gap_connect | ( | ble_gap_own_addr_t | own_addr_type,
|  | ble_gap_init_param_t * | p_init_param
| ) |  |

Start a legacy connection to a device.

Parameters

  [in] | own_addr_type | Own BD address source of the local device.
  [in] | p_init_param | Initiate parameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  This API is for legacy connection (BT Core Spec version <= 4.2).
  This API is asynchronous.
  event BLE_GAPC_EVT_CONNECTED will be triggered once the operation has completed or the connection has been completed.
  event BLE_GAPC_EVT_PEER_NAME_GOT will be triggered once the peer name has been got for the Name Discovery Procedure. See enum BLE_GAP_INIT_TYPE_NAME_DISC of type ble_gap_init_type_t.

## ◆ ble_gap_connect_cancel()

uint16_t ble_gap_connect_cancel | ( | void |  | ) |

Cancel an initiated connection.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_DISALLOWED | Operation is disallowed.

Note
  This API is asynchronous.
  event BLE_GAPC_EVT_CONNECT_CANCLE will be triggered once the operation has completed.

## ◆ ble_gap_connless_cte_trans_enable_set()

uint16_t ble_gap_connless_cte_trans_enable_set | ( | uint8_t | per_adv_index,
|  | bool | enable_flag
| ) |  |

Set connectionless CTE transmit enable.

Parameters

  [in] | per_adv_index | The index of the periodic advertising.
  [in] | enable_flag | Whether enable to transmit connectionless cte.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_connless_cte_trans_param_set()

uint16_t ble_gap_connless_cte_trans_param_set | ( | uint8_t | per_adv_index,
|  | gap_connless_cte_trans_param_t * | param
| ) |  |

Set connectionless CTE transmit parameters.

Parameters

  [in] | per_adv_index | The index of the periodic advertising.
  [in] | param | Connectionless CTE transmit arameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_connless_iq_sample_enable_set()

uint16_t ble_gap_connless_iq_sample_enable_set | ( | uint8_t | per_sync_index,
|  | bool | enable_flag,
|  | ble_gap_connless_iq_sample_param_t * | param
| ) |  |

Set connectionless IQ sampling enable.

Parameters

  [in] | per_sync_index | The index of the periodic syncronization instance.
  [in] | enable_flag | Whether enable connectionless iq sampling. if enable_flag is false, the param shall be NULL.
  [in] | param | Enable connectionless iq sampling parameters (see ble_gap_connless_iq_sample_param_t).

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_INVALID_PER_SYNC_IDX | Invalid periodic synchronization index supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_data_length_set()

uint16_t ble_gap_data_length_set | ( | uint16_t | sugg_max_tx_octet,
|  | uint16_t | sugg_max_tx_time
| ) |  |

Set suggested default LE data length.

Parameters

  [in] | sugg_max_tx_octet | Suggested value for the Controller's maximum transmitted number of payload octets to be used, the range is 27~251.
  [in] | sugg_max_tx_time | Suggested value for the Controller's maximum packet transmission time to be used, the range is 328~2120.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.

## ◆ ble_gap_dev_info_get()

uint16_t ble_gap_dev_info_get | ( | ble_gap_dev_info_get_type_t | type | ) |

Get the device information according to param type.

Note
  This API is asynchronous.
  Once the requested parameters has been got, the event BLE_GAPM_EVT_DEV_INFO_GOT will be called.

Parameters

  [in] | type | Param type.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_device_name_get()

uint16_t ble_gap_device_name_get | ( | uint8_t * | p_dev_name,
|  | uint16_t * | p_length
| ) |  |

Get GAP device name.

Parameters

  [out] | p_dev_name | The pointer to device name value, set to NULL to obtain the complete device name length.
  [in,out] | p_length | Length of the buffer pointed by p_dev_name, complete device name length on output.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_DATA_LENGTH | Invalid data size(s) supplied.

Note
  If device name was not set, the default device name "GOODIX_BLE" will be available.
  If the device name is longer than the size of the supplied buffer,p_len will return the complete device name length, and not the number of bytes actually returned in p_dev_name. The application may use this information to allocate a suitable buffer size.

## ◆ ble_gap_device_name_set()

uint16_t ble_gap_device_name_set | ( | ble_gap_dev_name_write_perm_t | write_perm,
|  | uint8_t const * | p_dev_name,
|  | uint16_t | length
| ) |  |

Set GAP device name.

Parameters

  [in] | write_perm | Write permissions of the device name characteristic.
  [in] | p_dev_name | The pointer to device name value. If p_dev_name is NULL, this function will only set write permissions of the device name.
  [in] | length | Device name length.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.

## ◆ ble_gap_ext_adv_param_set()

uint16_t ble_gap_ext_adv_param_set | ( | uint8_t | adv_idx,
|  | ble_gap_own_addr_t | own_addr_type,
|  | ble_gap_ext_adv_param_t * | p_adv_param
| ) |  |

Set extended parameters for advertising.

Note that this function must be called prior to advertising.

Parameters

  [in] | adv_idx | Advertising index, range is 0 to 4.
  [in] | own_addr_type | Own BD address source of the local device.
  [in] | p_adv_param | The advertising parameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  This API is for extended and periodic advertising (BT Core Spec version >= 5.0).

## ◆ ble_gap_ext_connect()

uint16_t ble_gap_ext_connect | ( | ble_gap_own_addr_t | own_addr_type,
|  | ble_gap_ext_init_param_t * | p_init_param
| ) |  |

Start an extended connection to a device.

Parameters

  [in] | own_addr_type | Own BD address source of the local device.
  [in] | p_init_param | Initiate parameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  This API is for extended connection (BT Core Spec version >= 5.0).
  This API is asynchronous.
  event BLE_GAPC_EVT_CONNECTED will be triggered once the operation has completed or the connection has been completed.

## ◆ ble_gap_ext_scan_param_set()

uint16_t ble_gap_ext_scan_param_set | ( | ble_gap_own_addr_t | own_addr_type,
|  | ble_gap_ext_scan_param_t * | p_scan_param
| ) |  |

Set extended parameters for scanning.

Note that this function must be called prior to scanning started.

Parameters

  [in] | own_addr_type | Own BD address source of the local device.
  [in] | p_scan_param | The scanning parameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  This API is for extended scanning (BT Core Spec version >= 5.0). The Scan window in p_scan_param should be enough to recieve one packet. For example. If you want to recieve packects with 1270 bytes on coded phy(S8), the scan_wd should be greater than 82ms. If you want to recieve packects with 1270 bytes on coded phy(S2), the scan_wd should be greater than 21ms.

## ◆ ble_gap_irk_set()

uint16_t ble_gap_irk_set | ( | ble_gap_sec_key_t * | p_irk | ) |

Set IRK used for resolvable random BD address generation (LSB first).

Parameters

  [in] | p_irk | Device IRK (Identity Resolving Key).

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_l2cap_params_set()

uint16_t ble_gap_l2cap_params_set | ( | uint16_t | max_mtu,
|  | uint16_t | max_mps,
|  | uint8_t | max_nb_lecb
| ) |  |

Set L2CAP related parameters.

Parameters

  [in] | max_mtu | Maximal MTU acceptable for device, the range is 65~512.
  [in] | max_mps | Maximal MPS Packet size acceptable for device (for COC SDU), the range is 65~max_mtu.
  [in] | max_nb_lecb | Maximum number of LE Credit based connection that can be established, this range is 0x00~0x20. The actual number is decided by resource available.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.

Note
  If these parameters are not set, the stack will config the default value as (max_mtu = 512, max_mps = 512 and max_nb_lecb = 10).

## ◆ ble_gap_lepsm_register()

uint16_t ble_gap_lepsm_register | ( | ble_gap_lepsm_register_t * | p_lepsm | ) |

Register a LE Protocol/Service Multiplexer.

Parameters

  [in] | p_lepsm | The lepsm information to be registerred.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_PSM_NUM | Invalid psm number.
  SDK_ERR_INVALID_PSM_EXCEEDED_MAX_PSM_NUM | The maximum psm number limit is exceeded.
  SDK_ERR_INVALID_PSM_ALREADY_REGISTERED | The psm number has been registered.

Note
  This API is asynchronous. BLE_GAPM_EVT_LEPSM_REGISTER event with op_id: BLE_GAP_OPCODE_LEPSM_REGISTER will be triggered.

## ◆ ble_gap_lepsm_unregister()

uint16_t ble_gap_lepsm_unregister | ( | uint16_t | le_psm | ) |

Unregister a LE Protocol/Service Multiplexer.

Parameters

  [in] | le_psm | LE Protocol/Service Multiplexer (1 to 255).

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PSM_NUM | Invalid psm number.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  This API is asynchronous. BLE_GAPM_EVT_LEPSM_UNREGISTER event with op_id: BLE_GAP_OPCODE_LEPSM_UNREGISTER will be triggered.

## ◆ ble_gap_pair_enable()

void ble_gap_pair_enable | ( | bool | enable | ) |

Decide whether to support the pair feature.

Parameters

  [in] | enable | Support flag.

## ◆ ble_gap_path_compensation_set()

uint16_t ble_gap_path_compensation_set | ( | int16_t | tx_path_comp,
|  | int16_t | rx_path_comp
| ) |  |

Set the RF path gain or loss between the RF transceiver and the antenna contributed by intermediate components.

Parameters

  [in] | tx_path_comp | RF TX Path Compensation value (from -128dB to 128dB, unit is 0.1dB).
  [in] | rx_path_comp | RF RX Path Compensation value (from -128dB to 128dB, unit is 0.1dB).

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | The parameter is invalid.

## ◆ ble_gap_per_adv_list_add()

uint16_t ble_gap_per_adv_list_add | ( | const ble_gap_period_adv_list_t * | p_pal_list | ) |

Add the devices into current periodic advertising list.

If periodic advertising list is full or there are duplicated entries, it will return error.

Note
  This API is asynchronous.
  Once the operation has completed, the event BLE_GAP_OPCODE_PER_ADV_LIST_SET will be called.

Parameters

  [in] | p_pal_list | Pointer to input periodic advertising list.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_LIST_ITEM_ALREADY_EXISTED | Item already existed in list.
  SDK_ERR_LIST_FULL | List is full.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_per_adv_list_clear()

uint16_t ble_gap_per_adv_list_clear | ( | void |  | ) |

Clear all the entries in the current periodic advertising list.

Note
  This API is asynchronous.
  Once the operation has completed, the event BLE_GAP_OPCODE_PER_ADV_LIST_SET will be called.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_DISALLOWED | Operation is disallowed.

## ◆ ble_gap_per_adv_list_del()

uint16_t ble_gap_per_adv_list_del | ( | const ble_gap_period_adv_list_t * | p_pal_list | ) |

Delete the devices out of periodic advertising list.

If the entries do not exist in the current list, an error will be returned.

Note
  This API is asynchronous.
  Once the operation has completed, the event BLE_GAP_OPCODE_PER_ADV_LIST_SET will be called.

Parameters

  [in] | p_pal_list | Pointer to input periodic advertising list.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_LIST_ITEM_NOT_FOUND | Item not found in list.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_per_adv_list_get()

uint16_t ble_gap_per_adv_list_get | ( | ble_gap_period_adv_list_t * | p_pal_list | ) |

Get the content of the whole periodic advertising list.

Parameters

  [in] | p_pal_list | Pointer to the output periodic advertising list.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_per_adv_report_ctrl()

uint16_t ble_gap_per_adv_report_ctrl | ( | uint8_t | per_sync_index,
|  | bool | enable_flag
| ) |  |

Control periodic advertising report.

Parameters

  [in] | per_sync_index | The index of the periodic syncronization instance.
  [in] | enable_flag | Per adv report flag. bit0: Reporting enabled(true report or false not report). bit1: Duplicate filtering enabled.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_per_sync_param_set()

uint16_t ble_gap_per_sync_param_set | ( | uint8_t | per_sync_idx,
|  | ble_gap_per_sync_param_t * | p_per_sync_param
| ) |  |

Set the parameters used for periodic sync.

Parameters

  [in] | per_sync_idx | Periodic synchronization index (range is 0 to 4).
  [in] | p_per_sync_param | Periodic synchronization parameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_PER_SYNC_IDX | Invalid periodic syncronization index supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_per_sync_start()

uint16_t ble_gap_per_sync_start | ( | uint8_t | per_sync_idx | ) |

Start to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets.

Parameters

  [in] | per_sync_idx | Periodic synchronization index (range is 0 to 4).

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_PER_SYNC_IDX | Invalid periodic syncronization index supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.

Note
  This API is asynchronous.
  event BLE_GAPM_EVT_SYNC_ESTABLISH will be triggered once the periodic advertising synchronization has been established.

## ◆ ble_gap_per_sync_stop()

uint16_t ble_gap_per_sync_stop | ( | uint8_t | per_sync_idx | ) |

Stop periodic synchronization.

Parameters

  [in] | per_sync_idx | Periodic synchronization index (range is 0 to 4).

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PER_SYNC_IDX | Invalid periodic syncronization index supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.

Note
  This API is asynchronous.
  event BLE_GAPM_EVT_SYNC_STOP will be triggered once the operation has completed.

## ◆ ble_gap_ppcp_get()

uint16_t ble_gap_ppcp_get | ( | ble_gap_conn_param_t * | p_conn_params | ) |

Get GAP Peripheral Preferred Connection Parameters.

Parameters

  [out] | p_conn_params | The pointer to PPCP values.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_ppcp_present_set()

void ble_gap_ppcp_present_set | ( | bool | present_flag | ) |

Set GAP Peripheral Preferred Connection Parameters present flag.

Parameters

  [in] | present_flag | Present or not.

## ◆ ble_gap_ppcp_set()

uint16_t ble_gap_ppcp_set | ( | ble_gap_conn_param_t const * | p_conn_params | ) |

Set GAP Peripheral Preferred Connection Parameters.

Parameters

  [in] | p_conn_params | The pointer to PPCP values.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_pref_phy_set()

void ble_gap_pref_phy_set | ( | uint8_t | tx_pref_phy,
|  | uint8_t | rx_pref_phy
| ) |  |

Set the preferred values for the transmitter PHY and receiver PHY.

Parameters

  [in] | tx_pref_phy | A bit field that indicates the transmitter PHYs that the Host prefers the Controller to use(see GAP PHYs (bitmask)).
  [in] | rx_pref_phy | A bit field that indicates the receiver PHYs that the Host prefers the Controller to use(see GAP PHYs (bitmask)).

## ◆ ble_gap_privacy_mode_set()

uint16_t ble_gap_privacy_mode_set | ( | ble_gap_bdaddr_t | peer_addr,
|  | ble_gap_privacy_mode_t | mode
| ) |  |

Set privacy mode for peer device.

Parameters

  [in] | peer_addr | The peer address.
  [in] | mode | Privacy mode (see ble_gap_privacy_mode_t).

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_privacy_params_set()

uint16_t ble_gap_privacy_params_set | ( | uint16_t | renew_dur,
|  | bool | enable_flag
| ) |  |

Set privacy related parameters.

Parameters

  [in] | renew_dur | Duration before regenerating a device address when privacy is enabled in seconds. Range: 0x0001 (1s) ~ 0xA1B8 (11.5 hr). The suggested time is 900s(15 minutes).
  [in] | enable_flag | Indicate the controller privacy is enabled or disabled.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.

## ◆ ble_gap_register_conless_iq_report_cb()

void ble_gap_register_conless_iq_report_cb | ( | void(*)(uint8_t per_sync_idx, const ble_gap_connless_iq_report_t *iq_report) | cb | ) |

Register connectionless iq report event callback.

Parameters

  [in] | cb | The callback for connectionless IQ report event.

Return values

  void. |

## ◆ ble_gap_rpa_list_get()

uint16_t ble_gap_rpa_list_get | ( | ble_gap_ral_dev_list_t * | p_rpa_list,
|  | uint8_t | max_num
| ) |  |

Get the RPA list info.

Parameters

  [in] | p_rpa_list | Pointer to the output RPA list.
  [in] | max_num | Max number of rpa list can be gotten.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_rslv_addr_read()

uint16_t ble_gap_rslv_addr_read | ( | ble_gap_rslv_addr_read_op_id_t | op_code,
|  | ble_gap_bdaddr_t | peer_iden_addr
| ) |  |

Read peer or local resolvable address, this address generated by controller.

Parameters

  [in] | op_code | The operation code (see ble_gap_rslv_addr_read_op_id_t).
  [in] | peer_iden_addr | The peer identity address.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.

## ◆ ble_gap_scan_param_set()

uint16_t ble_gap_scan_param_set | ( | ble_gap_own_addr_t | own_addr_type,
|  | ble_gap_scan_param_t * | p_scan_param
| ) |  |

Set parameters for scanning.

Note that this function must be called prior to scanning started.

Parameters

  [in] | own_addr_type | Own BD address source of the local device.
  [in] | p_scan_param | The scanning parameters.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  This API is for legacy scanning (BT Core Spec version <= 4.2).

## ◆ ble_gap_scan_start()

uint16_t ble_gap_scan_start | ( | void |  | ) |

Start scanning.

Note
  This API is asynchronous.
  Once the advertising report has been received, the event BLE_GAPM_EVT_ADV_REPORT will be called.
  Once the scanning has been stopped, the event BLE_GAPM_EVT_SCAN_STOP will be called.
  Once the operation has completed, the event BLE_GAPM_EVT_SCAN_START will be called.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_DISALLOWED | Operation is disallowed.

## ◆ ble_gap_scan_stop()

uint16_t ble_gap_scan_stop | ( | void |  | ) |

Stop scanning.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_DISALLOWED | Operation is disallowed.

Note
  This API is asynchronous.
  event BLE_GAPM_EVT_SCAN_STOP will be triggered once the operation has completed or the scanning has been stopped.

## ◆ ble_gap_set_gdx_ranging_param()

uint16_t ble_gap_set_gdx_ranging_param | ( | uint32_t | base_addr,
|  | uint8_t | cte_len
| ) |  |

Set ranging parameter.

Parameters

  [in] | base_addr | The base address.
  [in] | cte_len | The length for cte.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.

## ◆ ble_gap_tx_power_get()

uint16_t ble_gap_tx_power_get | ( | ble_gap_actv_role_t | role,
|  | uint8_t | index,
|  | int8_t * | txpwr_dbm
| ) |  |

Get the tx power.

Parameters

  [in] | role | Select the role to Get tx power. ble_gap_actv_role_t for possible roles.
  [in] | index | The idx parameter is interpreted on role. If role is BLE_GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising. If role is BLE_GAP_ACTIVITY_ROLE_CON, it's the index of connection. For all other roles, it should be ignored.
  [out] | txpwr_dbm | Tx power, unit(dBm). support value:[-20, -13, -9, -5, -2, 0, 1, 2, 3, 4, 5, 6, 7, 8]

Return values

  SDK_SUCCESS | Operation is Success.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.

## ◆ ble_gap_tx_power_set()

uint16_t ble_gap_tx_power_set | ( | ble_gap_actv_role_t | role,
|  | uint8_t | index,
|  | int8_t | txpwr_dbm
| ) |  |

Set the tx power.

Parameters

  [in] | role | Select the role to set tx power. ble_gap_actv_role_t for possible roles.
  [in] | index | The idx parameter is interpreted on role. -If role is BLE_GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising. -If role is BLE_GAP_ACTIVITY_ROLE_CON, it's the index of connection. -For all other roles, it should be ignored.
  [in] | txpwr_dbm | Tx power, unit(dBm). support value:[-20, -13, -9, -5, -2, 0, 1, 2, 3, 4, 5, 6, 7, 8]

Return values

  SDK_SUCCESS | Operation is Success.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.

## ◆ ble_gap_update_adv_data()

uint16_t ble_gap_update_adv_data | ( | uint8_t | adv_idx,
|  | ble_gap_adv_data_type_t | type,
|  | const uint8_t * | p_data,
|  | uint16_t | length
| ) |  |

Update Advertising Data, Scan Response Data and Periodic Advertising Data.

See ENUM ble_gap_ad_type_t for ADV Type definitions. See ENUM ble_gap_adv_flags_t for ADV flag definitions.

Parameters

  [in] | adv_idx | Advertising index, range is 0 to 4.
  [in] | type | Data type.
  [in] | p_data | The data pointer.
  [in] | length | Data length.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_ADV_IDX | Invalid advertising index supplied.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

Note
  User should not add extra Flags AD type as the BLE Stack has added the Flags AD type already.

## ◆ ble_gap_whitelist_add()

uint16_t ble_gap_whitelist_add | ( | const ble_gap_white_list_t * | p_whitelist | ) |

Add the devices into current white list.

If white list is full or there are duplicated entries, it will return error.

Note
  This API is asynchronous.
  Once the operation has completed, the event BLE_GAP_OPCODE_WHITELIST_SET will be called.

Parameters

  [in] | p_whitelist | Pointer to input white list.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_LIST_ITEM_ALREADY_EXISTED | Item already existed in list.
  SDK_ERR_LIST_FULL | List is full.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_whitelist_clear()

uint16_t ble_gap_whitelist_clear | ( | void |  | ) |

Clear all the entries in the current white list.

Note
  This API is asynchronous.
  once the operation has completed, the event BLE_GAP_OPCODE_WHITELIST_SET will be called.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_whitelist_del()

uint16_t ble_gap_whitelist_del | ( | const ble_gap_white_list_t * | p_whitelist | ) |

Delete the devices out of current white list.

If the entries do not exist in the current white list, it will return error.

Note
  This API is asynchronous.
  Once the operation has completed, the event BLE_GAP_OPCODE_WHITELIST_SET will be called.

Parameters

  [in] | p_whitelist | Pointer to input white list.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_LIST_ITEM_NOT_FOUND | Item not found in list.
  SDK_ERR_DISALLOWED | Operation is disallowed.
  SDK_ERR_INVALID_PARAM | Invalid parameter supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gap_whitelist_get()

uint16_t ble_gap_whitelist_get | ( | ble_gap_white_list_t * | p_whitelist | ) |

Get the content of the whole white list.

Parameters

  [in] | p_whitelist | Pointer to the output white list.

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.