Functions
Functions
BLE » Generic Access Profile (GAP) » Generic Access Profile (GAP) Management

## Functions
void | ble_gap_pair_enable (bool enable)
| Decide whether to support the pair feature. More...
uint16_t | ble_gap_addr_set (gap_bdaddr_t const *p_addr)
| Set the device identity address (public or random static). More...
uint16_t | ble_gap_addr_get (gap_bdaddr_t *p_addr)
| Get the device identity address (public or random static). More...
uint16_t | ble_gap_tx_power_set (gap_activity_role_t role, uint8_t index, int8_t txpwr_dbm)
| Set the tx power. More...
uint16_t | ble_gap_tx_power_get (gap_activity_role_t role, uint8_t index, int8_t *txpwr_dbm)
| Get the tx power. More...
uint16_t | ble_gap_default_tx_power_set (int8_t txpwr_dbm)
| Set the default tx power for all roles. More...
uint16_t | ble_gap_default_tx_power_get (int8_t *txpwr_dbm)
| Get the default tx power for all roles. More...
uint16_t | ble_gap_irk_set (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...
uint16_t | ble_gap_chnl_map_set (gap_chnl_map_t *p_chnl_map)
| Set advertising channel map before advertising starts. More...
uint16_t | ble_gap_bond_devs_get (bond_dev_list_t *p_bond_list)
| Get all bonded devices. More...
uint16_t | ble_gap_bond_dev_addr_get (uint8_t conn_idx, gap_bdaddr_t *p_peer_addr)
| Get BD address of the bonded device. More...
uint16_t | ble_gap_bond_devs_clear (void)
| Clear all bonded devices. More...
uint16_t | ble_gap_bond_dev_del (const gap_bdaddr_t *p_peer_addr)
| Delete a bond device with the specified BD address. More...
uint16_t | ble_gap_whitelist_get (white_list_t *p_whitelist)
| Get the content of the whole white list. More...
uint16_t | ble_gap_whitelist_add (const 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. More...
uint16_t | ble_gap_whitelist_del (const 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. 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 (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 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. More...
uint16_t | ble_gap_per_adv_list_del (const 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. 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 (ral_dev_list_t *p_rpa_list)
| Get the RPA list info. More...
uint16_t | ble_gap_dev_info_get (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, gap_own_addr_t own_addr_type, gap_adv_param_t *p_adv_param)
| Set parameters for advertising. Note that this function must be called prior to advertising started. More...
uint16_t | ble_gap_ext_adv_param_set (uint8_t adv_idx, gap_own_addr_t own_addr_type, gap_ext_adv_param_t *p_adv_param)
| Set extended parameters for advertising. Note that this function must be called prior to advertising. More...
uint16_t | ble_gap_adv_data_set (uint8_t adv_idx, 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 gap_ad_type_t for ADV Type definitions. See ENUM gap_adv_flags_t for ADV flag definitions. More...
uint16_t | ble_gap_update_adv_data (uint8_t adv_idx, 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 gap_ad_type_t for ADV Type definitions. See ENUM gap_adv_flags_t for ADV flag definitions. More...
uint16_t | ble_gap_adv_start (uint8_t adv_idx, 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 (gap_own_addr_t own_addr_type, gap_scan_param_t *p_scan_param)
| Set parameters for scanning. Note that this function must be called prior to scanning started. More...
uint16_t | ble_gap_ext_scan_param_set (gap_own_addr_t own_addr_type, gap_ext_scan_param_t *p_scan_param)
| Set extended parameters for scanning. Note that this function must be called prior to scanning started. 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, 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 (gap_own_addr_t own_addr_type, gap_init_param_t *p_init_param)
| Start a legacy connection to a device. More...
uint16_t | ble_gap_ext_connect (gap_own_addr_t own_addr_type, 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...
void | ble_gap_ppcp_present_set (bool present_flag)
| Set GAP Peripheral Preferred Connection Parameters present flag. More...
uint16_t | ble_gap_ppcp_set (gap_conn_param_t const *p_conn_params)
| Set GAP Peripheral Preferred Connection Parameters. More...
uint16_t | ble_gap_ppcp_get (gap_conn_param_t *p_conn_params)
| Get GAP Peripheral Preferred Connection Parameters. More...
uint16_t | ble_gap_device_name_set (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 (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 (gap_bdaddr_t peer_addr, privacy_mode_t mode)
| Set privacy mode for peer device. More...
uint16_t | ble_gap_rslv_addr_read (gap_rslv_addr_read_op_id_t op_code, gap_bdaddr_t peer_iden_addr)
| Read peer or local resolvable address. More...
uint16_t | ble_gap_reslv_rpa_addr (uint8_t *reslv_addr, uint8_t src_info, reslv_rpa_addr_callback_t cb)
| Resolve the rpa address. More...
uint16_t | ble_gap_update_conn_param_method_set (uint8_t conn_idx, bool use_l2cap_flag)
| Set the method for updating connection parameter. More...
void | ble_gap_rpa_addr_report_cb_register (rpa_addr_report_callback_t cb)
| Set the cb for rpa address report. More...

## Detailed Description

## Function Documentation

## ◆ ble_gap_addr_get()

uint16_t ble_gap_addr_get | ( | 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 | ( | 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,
|  | 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 gap_ad_type_t for ADV Type definitions. See ENUM 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,
|  | gap_own_addr_t | own_addr_type,
|  | 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,
|  | 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 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 gap_adv_prop_t and passed in ble_gap_ext_adv_param_set function, gap_cb_fun_t::app_gap_scan_req_ind_cb will be called once a scan request has been received.
  gap_cb_fun_t::app_gap_adv_start_cb will be called 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.
  gap_cb_fun_t::app_gap_adv_stop_cb will be called 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_addr_get()

uint16_t ble_gap_bond_dev_addr_get | ( | uint8_t | conn_idx,
|  | gap_bdaddr_t * | p_peer_addr
| ) |  |

Get BD address of the bonded device.

Parameters

  [in] | conn_idx | The index of connection.
  [in] | p_peer_addr | Pointer to the peer BD addrss

Return values

  SDK_SUCCESS | Operation is successful.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_PARAM | The parameter is invalid.

## ◆ ble_gap_bond_dev_del()

uint16_t ble_gap_bond_dev_del | ( | const 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 | ( | bond_dev_list_t * | p_bond_list | ) |

Get 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.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.

## ◆ ble_gap_chnl_map_set()

uint16_t ble_gap_chnl_map_set | ( | gap_chnl_map_t * | p_chnl_map | ) |

Set advertising channel map before advertising starts.

Parameters

  [in] | p_chnl_map | Bitmask of LE channel map. See enum 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.

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_CHNL_MAP_SET will be called once the operation has completed.

## ◆ ble_gap_connect()

uint16_t ble_gap_connect | ( | gap_own_addr_t | own_addr_type,
|  | 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.
  gap_cb_fun_t::app_gap_connect_cb will be called once the operation has completed or the connection has been completed.
  gap_cb_fun_t::app_gap_peer_name_ind_cb will be called once the peer name has been got for the Name Discovery Procedure. See enum GAP_INIT_TYPE_NAME_DISC of type 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.
  gap_cb_fun_t::app_gap_connect_cancel_cb will be called once the operation has completed.

## ◆ 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_default_tx_power_get()

uint16_t ble_gap_default_tx_power_get | ( | int8_t * | txpwr_dbm | ) |

Get the default tx power for all roles.

Parameters

  [in] | txpwr_dbm | The value of the tx power, Range: -20dbm to 7dbm.

Return values

  SDK_SUCCESS | Operation is Success.

## ◆ ble_gap_default_tx_power_set()

uint16_t ble_gap_default_tx_power_set | ( | int8_t | txpwr_dbm | ) |

Set the default tx power for all roles.

Note
  This function should be called before BLE stack init.

Parameters

  [in] | txpwr_dbm | The value of the tx power, Range: -20dbm to 7dbm.

Return values

  SDK_SUCCESS | Operation is Success.

## ◆ ble_gap_dev_info_get()

uint16_t ble_gap_dev_info_get | ( | gap_dev_info_get_type_t | type | ) |

Get the device information according to param type.

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.

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_dev_info_get_cb with the specified op_id (see gap_dev_info_get_type_t) will be called once the requested parameters has been got.

## ◆ 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 | ( | 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,
|  | gap_own_addr_t | own_addr_type,
|  | 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 | ( | gap_own_addr_t | own_addr_type,
|  | 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.
  gap_cb_fun_t::app_gap_connect_cb will be called 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 | ( | gap_own_addr_t | own_addr_type,
|  | 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 | ( | 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 | ( | 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. gap_cb_fun_t::app_gap_psm_manager_cb callback with op_id: GAP_OPCODE_LEPSM_REGISTER will be called.

## ◆ 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.
  app_gap_psm_manager_cb will be called once the operation has completed, gap_cb_fun_t::app_gap_psm_manager_cb callback with op_id: GAP_OPCODE_LEPSM_UNREGISTER will be called.

## ◆ 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 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.

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.

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_PER_ADV_LIST_SET will be called once the operation has completed.

## ◆ 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.
  gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_PER_ADV_LIST_SET will be called once the operation has completed.

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 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.

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.

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_PER_ADV_LIST_SET will be called once the operation has completed.

## ◆ ble_gap_per_adv_list_get()

uint16_t ble_gap_per_adv_list_get | ( | 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_sync_param_set()

uint16_t ble_gap_per_sync_param_set | ( | uint8_t | per_sync_idx,
|  | 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.
  gap_cb_fun_t::app_gap_sync_establish_cb will be called 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.
  gap_cb_fun_t::app_gap_stop_sync_cb will be called once the operation has completed.

## ◆ ble_gap_ppcp_get()

uint16_t ble_gap_ppcp_get | ( | 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 | ( | 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 | ( | gap_bdaddr_t | peer_addr,
|  | privacy_mode_t | mode
| ) |  |

Set privacy mode for peer device.

Parameters

  [in] | peer_addr | The peer address.
  [in] | mode | Privacy mode (see 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_reslv_rpa_addr()

uint16_t ble_gap_reslv_rpa_addr | ( | uint8_t * | reslv_addr,
|  | uint8_t | src_info,
|  | reslv_rpa_addr_callback_t | cb
| ) |  |

Resolve the rpa address.

Parameters

  [in] | reslv_addr | rpa address.
  [in] | src_info | Information used retrieve requester (src_info >= 10).
  [in] | cb | Function that will handle the resolved result.

Return values

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

## ◆ ble_gap_rpa_addr_report_cb_register()

void ble_gap_rpa_addr_report_cb_register | ( | rpa_addr_report_callback_t | cb | ) |

Set the cb for rpa address report.

Parameters

  [in] | cb | the cb for rpa address report.

## ◆ ble_gap_rpa_list_get()

uint16_t ble_gap_rpa_list_get | ( | ral_dev_list_t * | p_rpa_list | ) |

Get the RPA list info.

Parameters

  [in] | p_rpa_list | Pointer to the output RPA list.

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 | ( | gap_rslv_addr_read_op_id_t | op_code,
|  | gap_bdaddr_t | peer_iden_addr
| ) |  |

Read peer or local resolvable address.

Parameters

  [in] | op_code | The operation code (see 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 | ( | gap_own_addr_t | own_addr_type,
|  | 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.

Return values

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

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_adv_report_ind_cb will be called once the advertising report has been received.
  gap_cb_fun_t::app_gap_scan_stop_cb will be called once the scanning has been stopped.
  gap_cb_fun_t::app_gap_scan_start_cb will be called once the operation has completed.

## ◆ 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.
  gap_cb_fun_t::app_gap_scan_stop_cb will be called once the operation has completed or the scanning has been stopped.

## ◆ ble_gap_tx_power_get()

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

Get the tx power.

Parameters

  [in] | role | Select the role to Get tx power. gap_activity_role_t for possible roles.
  [in] | index | The idx parameter is interpreted on role. -If role is GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising. -If role is GAP_ACTIVITY_ROLE_CON, it's the index of connection. -For all other roles, it should be ignored.
  [in] | txpwr_dbm | The value of the tx power, Range: -20dbm to 7dbm.

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 | ( | gap_activity_role_t | role,
|  | uint8_t | index,
|  | int8_t | txpwr_dbm
| ) |  |

Set the tx power.

Parameters

  [in] | role | Select the role to set tx power. gap_activity_role_t for possible roles.
  [in] | index | The idx parameter is interpreted on role. -If role is GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising. -If role is GAP_ACTIVITY_ROLE_CON, it's the index of connection. -For all other roles, it should be ignored.
  [in] | txpwr_dbm | The value of the tx power, Range: -20dbm to 7dbm.

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,
|  | 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 gap_ad_type_t for ADV Type definitions. See ENUM 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_update_conn_param_method_set()

uint16_t ble_gap_update_conn_param_method_set | ( | uint8_t | conn_idx,
|  | bool | use_l2cap_flag
| ) |  |

Set the method for updating connection parameter.

Parameters

  [in] | conn_idx | Connection index.
  [in] | use_l2cap_flag | Preferred to use l2cap to update connection parameter.

Return values

  SDK_SUCCESS | Operation is Success.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.

## ◆ ble_gap_whitelist_add()

uint16_t ble_gap_whitelist_add | ( | const 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.

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.

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_WHITELIST_SET will be called once the operation has completed.

## ◆ ble_gap_whitelist_clear()

uint16_t ble_gap_whitelist_clear | ( | void |  | ) |

Clear all the entries in the current white list.

Return values

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

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_WHITELIST_SET will be called once the operation has completed.

## ◆ ble_gap_whitelist_del()

uint16_t ble_gap_whitelist_del | ( | const 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.

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.

Note
  This API is asynchronous.
  gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_WHITELIST_SET will be called once the operation has completed.

## ◆ ble_gap_whitelist_get()

uint16_t ble_gap_whitelist_get | ( | 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.