LE Extended ADV Exported Functions

group LE_EXTENDED_ADV_Exported_Functions

Functions

T_GAP_CAUSE ble_ext_adv_mgr_register_callback(P_FUN_GAP_APP_CB app_callback, uint8_t adv_handle)

Used to register the application callback function for each ADV set.

Parameters:

app_callback -- [in] Application callback function: P_FUN_GAP_APP_CB.
adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_init_adv_params(uint8_t *adv_handle, uint16_t adv_event_prop, uint32_t primary_adv_interval_min, uint32_t primary_adv_interval_max, T_GAP_LOCAL_ADDR_TYPE own_address_type, T_GAP_REMOTE_ADDR_TYPE peer_address_type, uint8_t *p_peer_address, T_GAP_ADV_FILTER_POLICY filter_policy, uint16_t adv_data_len, uint8_t *p_adv_data, uint16_t scan_data_len, uint8_t *p_scan_data, uint8_t *random_address)

Used to create an ADV handle and initialize ADV parameters, ADV data, scan response data, and random address.

This API shall only be called after ble_mgr_init and shall only be called once. This API cannot be used with ble_ext_adv_mgr_init_adv_params_all at the same time. That means in an ADV set ble_ext_adv_mgr_init_adv_params_all and ble_ext_adv_mgr_init_adv_params can only choose one.

Example usage

void app_ble_common_adv_init(void)
{   //app_ble_common_adv_data and scan_rsp_data shall point to a global memory.
    ble_ext_adv_mgr_init_adv_params(&le_common_adv.adv_handle, adv_event_prop, adv_interval_min,
                                adv_interval_max, own_address_type, peer_address_type, peer_address,
                                filter_policy, 23 + data_len, app_ble_common_adv_data,
                                scan_rsp_data_len, scan_rsp_data, le_random_addr);

    ble_ext_adv_mgr_register_callback(app_ble_common_adv_callback, le_common_adv.adv_handle);
}

Parameters:

adv_handle -- [out] LE ADV handle, each ADV set has an ADV handle.
adv_event_prop -- [in] T_LE_EXT_ADV_LEGACY_ADV_PROPERTY.
primary_adv_interval_min -- [in] Minimum advertising interval for undirected and low duty directed advertising. In units of 0.625ms, range: 0x000020 to 0xFFFFFF.
primary_adv_interval_max -- [in] Maximum advertising interval for undirected and low duty directed advertising. In units of 0.625ms, range: 0x000020 to 0xFFFFFF.
own_address_type -- [in] T_GAP_LOCAL_ADDR_TYPE.
peer_address_type -- [in] T_GAP_REMOTE_ADDR_TYPE.
p_peer_address -- [in] If not used, set default value NULL.
filter_policy -- [in] T_GAP_ADV_FILTER_POLICY.
adv_data_len -- [in] If APP doesn't want to set ADV data, set default length 0.
p_adv_data -- [in] LE ext ADV mgr will not reallocate memory for ADV data, so p_adv_data shall point to a global memory. If APP doesn't want to set ADV data, set default value NULL.
scan_data_len -- [in] If APP doesn't want to set scan response data, set default length 0.
p_scan_data -- [in] LE ext ADV mgr will not reallocate memory for scan response data, so p_scan_data shall point to a global memory. If APP doesn't want to set scan response data, set default value NULL.
random_address -- [in] If APP doesn't want to set a random address, set default value NULL.

Returns:

Cause. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_init_adv_params_all(uint8_t *adv_handle, uint16_t adv_event_prop, uint8_t adv_sid, uint8_t tx_power, uint32_t primary_adv_interval_min, uint32_t primary_adv_interval_max, uint8_t primary_adv_channel_map, T_GAP_PHYS_PRIM_ADV_TYPE primary_adv_phy, uint8_t secondary_adv_max_skip, T_GAP_PHYS_TYPE secondary_adv_phy, T_GAP_LOCAL_ADDR_TYPE own_address_type, T_GAP_REMOTE_ADDR_TYPE peer_address_type, uint8_t *p_peer_address, T_GAP_ADV_FILTER_POLICY filter_policy, uint16_t adv_data_len, uint8_t *p_adv_data, uint16_t scan_data_len, uint8_t *p_scan_data, uint8_t *random_address)

Used to create an ADV handle and initialize ADV parameters, ADV data, scan response data, and random address.

This API shall only be called after ble_mgr_init and shall only be called once. This API cannot be used with ble_ext_adv_mgr_init_adv_params at the same time. That means in an ADV set ble_ext_adv_mgr_init_adv_params_all and ble_ext_adv_mgr_init_adv_params can only choose one.

Example usage

void app_ble_common_adv_init(void)
{   //app_ble_common_adv_data and scan_rsp_data shall point to a global memory.
    ble_ext_adv_mgr_init_adv_params_all(&le_common_adv.adv_handle, adv_event_prop, adv_sid, tx_power,
                                        primary_adv_interval_min, primary_adv_interval_max,
                                        primary_adv_channel_map, primary_adv_phy,
                                        secondary_adv_max_skip, secondary_adv_phy,
                                        own_address_type, peer_address_type,
                                        p_peer_address,
                                        filter_policy, adv_data_len, p_adv_data,
                                        scan_data_len, p_scan_data, random_address);

    ble_ext_adv_mgr_register_callback(app_ble_common_adv_callback, le_common_adv.adv_handle);
}

Parameters:

adv_handle -- [out] LE ADV handle, each ADV set has an ADV handle.
adv_event_prop -- [in] T_LE_EXT_ADV_LEGACY_ADV_PROPERTY.
adv_sid -- [in] Specify the value to be transmitted in the Advertising SID subfield of those advertising channels.
tx_power -- [in] Advertising Tx power.
primary_adv_interval_min -- [in] Minimum advertising interval for undirected and low duty directed advertising. In units of 0.625ms, range: 0x000020 to 0xFFFFFF.
primary_adv_interval_max -- [in] Maximum advertising interval for undirected and low duty directed advertising. In units of 0.625ms, range: 0x000020 to 0xFFFFFF.
primary_adv_channel_map -- [in] A bit field that indicates the advertising channels that shall be used when transmitting advertising packets. Advertising Channel Map.
primary_adv_phy -- [in] Indicate the PHY on which the advertising packets are transmitted on the primary advertising channel.
secondary_adv_max_skip -- [in] Maximum number of advertising events that can be skipped. Usually set to zero.
secondary_adv_phy -- [in] Indicate the PHY on which the advertising packets are transmitted on the secondary advertising channel.
own_address_type -- [in] T_GAP_LOCAL_ADDR_TYPE.
peer_address_type -- [in] T_GAP_REMOTE_ADDR_TYPE.
p_peer_address -- [in] If not used, set default value NULL.
filter_policy -- [in] T_GAP_ADV_FILTER_POLICY.
adv_data_len -- [in] If APP doesn't want to set ADV data, set default length 0.
p_adv_data -- [in] LE ext ADV mgr will not reallocate memory for ADV data, so p_adv_data shall point to a global memory. If APP doesn't want to set ADV data, set default value NULL.
scan_data_len -- [in] If APP doesn't want to set scan response data, set default length 0.
p_scan_data -- [in] LE ext ADV mgr will not reallocate memory for scan response data, so p_scan_data shall point to a global memory. If APP doesn't want to set scan response data, set default value NULL.
random_address -- [in] If APP doesn't want to set a random address, set default value NULL.

Returns:

T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_enable(uint8_t adv_handle, uint16_t duration_10ms)

Enable an advertising set.

Example usage

void test(void)
{
    uint16_t duration = 0;
    if(ble_ext_adv_mgr_get_adv_state(adv_handle) == BLE_EXT_ADV_MGR_ADV_DISABLED)
    {
     ble_ext_adv_mgr_enable(adv_handle,duration);
    }
    else
    {
     APP_PRINT_INFO0("this ADV set has already in enabled state");
    }
}

Note

If APP wants to use ble_ext_adv_mgr_enable to enable an ADV set, please get LE ADV mgr ADV state firstly, and when LE ADV mgr ADV state is BLE_EXT_ADV_MGR_ADV_DISABLED, APP can use ble_ext_adv_mgr_enable to enable this ADV set; otherwise, this ADV set is already in enabled state, there is no need to call this API again.

Parameters:

adv_handle -- [in] Identify an advertising set, which is assigned by ble_ext_adv_mgr_init_adv_params.
duration_10ms -- [in] If non-zero, indicates the duration that advertising set is enabled.
- 0x0000: No advertising duration.
- 0x0001-0xFFFF: Advertising duration, in units of 10ms.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result.

T_GAP_CAUSE ble_ext_adv_mgr_disable(uint8_t adv_handle, uint8_t app_cause)

Disable an advertising set.

Example usage

void test(void)
{
   if(ble_ext_adv_mgr_get_adv_state(adv_handle) == BLE_EXT_ADV_MGR_ADV_ENABLED)
   {
    ble_ext_adv_mgr_disable(adv_handle,0xFF);
   }
   else
   {
    APP_PRINT_INFO0("this ADV set has already in disabled state");
   }

}

Note

If wanting to use ble_ext_adv_mgr_disable to disable an ADV set, please get LE ADV mgr ADV state firstly, and when LE ADV mgr ADV state is BLE_EXT_ADV_MGR_ADV_ENABLED, it is possible to use ble_ext_adv_mgr_disable to disable this ADV set; otherwise, this ADV set is already in disabled state, there is no need to call this API again.

Parameters:

adv_handle -- [in] Identify an advertising set, which is assigned by ble_ext_adv_mgr_init_adv_params.
app_cause -- [in] The reason for disabling an ADV set.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result.

T_GAP_CAUSE ble_ext_adv_mgr_disable_all(uint8_t app_cause)

Disable all advertising sets.

Parameters:

app_cause -- [in] The reason for disabling all ADV sets.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure.

Returns:

Operation result.

T_GAP_CAUSE ble_ext_adv_mgr_set_adv_data(uint8_t adv_handle, uint16_t adv_data_len, uint8_t *p_adv_data)

Used to update ADV data.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] Identify an advertising set, which is assigned by ble_ext_adv_mgr_init_adv_params.
adv_data_len -- [in] ADV data length.
p_adv_data -- [in] LE ext ADV mgr will not reallocate memory for ADV data, so p_adv_data shall point to a global memory.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result.

T_GAP_CAUSE ble_ext_adv_mgr_set_random(uint8_t adv_handle, uint8_t *random_address)

Used to update random address.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] Identify an advertising set, which is assigned by ble_ext_adv_mgr_init_adv_params.
random_address -- [in] Random address.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result.

T_GAP_CAUSE ble_ext_adv_mgr_set_scan_response_data(uint8_t adv_handle, uint16_t scan_data_len, uint8_t *p_scan_data)

Used to update scan response data.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] Identify an advertising set, which is assigned by ble_ext_adv_mgr_init_adv_params.
scan_data_len -- [in] Scan response data length.
p_scan_data -- [in] LE ext ADV mgr will not reallocate memory for scan response data, so p_scan_data shall point to a global memory.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result.

T_GAP_CAUSE ble_ext_adv_mgr_set_multi_param(uint8_t adv_handle, uint8_t *random_address, uint16_t adv_interval, uint16_t adv_data_len, uint8_t *p_adv_data, uint16_t scan_data_len, uint8_t *p_scan_data)

Used to set random_address, ADV interval, ADV data and scan response data.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
random_address -- [in] Random address.
adv_interval -- [in] ADV interval.
adv_data_len -- [in] ADV data length.
p_adv_data -- [in] LE ext ADV mgr will not reallocate memory for ADV data, so p_adv_data shall point to a global memory.
scan_data_len -- [in] Scan response data length.
p_scan_data -- [in] LE ext ADV mgr will not reallocate memory for scan response data, so p_scan_data shall point to a global memory.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_adv_interval(uint8_t adv_handle, uint16_t adv_interval)

Used to update ADV interval.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
adv_interval -- [in] ADV interval.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_adv_tx_power(uint8_t adv_handle, int8_t adv_tx_power)

Used to update ADV tx power.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
adv_tx_power -- [in] Range: -127 to +20, Units: dBm, 0x7F Host has no preference, the default value is 0x7F.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_adv_event_prop(uint8_t adv_handle, uint16_t adv_event_prop)

Used to update adv_event_prop.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
adv_event_prop -- [in] T_LE_EXT_ADV_LEGACY_ADV_PROPERTY.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_adv_phy(uint8_t adv_handle, T_GAP_PHYS_PRIM_ADV_TYPE primary_adv_phy, T_GAP_PHYS_TYPE secondary_adv_phy)

Used to update primary and secondary ADV phy.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
primary_adv_phy -- [in] T_GAP_PHYS_PRIM_ADV_TYPE.
secondary_adv_phy -- [in] T_GAP_PHYS_TYPE.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_peer_addr(uint8_t adv_handle, T_GAP_REMOTE_ADDR_TYPE peer_addr_type, uint8_t *peer_addr)

Used to update peer address.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Added Since 2.11.1.0:

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
peer_addr_type -- [in] T_GAP_REMOTE_ADDR_TYPE.
peer_addr -- [in] Peer address.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_NOT_FIND -- Operation failure, the advertising handle is not found.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_channel_map(uint8_t adv_handle, uint8_t primary_adv_channel_map)

Used to update primary_adv_channel_map.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Added Since 2.12.1.0:

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
primary_adv_channel_map -- [in] GAP_ADVCHAN_ALL or GAP_ADVCHAN_37 or GAP_ADVCHAN_38 or GAP_ADVCHAN_39.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_filter_policy(uint8_t adv_handle, T_GAP_ADV_FILTER_POLICY filter_policy)

Used to update filter policy.

This API shall be used after ble_ext_adv_mgr_init_adv_params_all or ble_ext_adv_mgr_init_adv_params.

Added Since 2.12.1.0:

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
filter_policy -- [in] T_GAP_ADV_FILTER_POLICY.

Returns:

Operation result. T_GAP_CAUSE.

T_GAP_CAUSE ble_ext_adv_mgr_change_own_address_type(uint8_t adv_handle, T_GAP_LOCAL_ADDR_TYPE own_addr_type)

Used to update own address type, this API shall be used after GAP init ready.

Experimental Added Since 2.14.0.0:

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
own_addr_type -- [in] T_GAP_LOCAL_ADDR_TYPE.

Returns:

Operation result. T_GAP_CAUSE.

T_BLE_EXT_ADV_MGR_STATE ble_ext_adv_mgr_get_adv_state(uint8_t adv_handle)

Used to get ble_ext_adv_mgr_adv_state T_BLE_EXT_ADV_MGR_STATE.

Parameters:: adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
Returns:: T_BLE_EXT_ADV_MGR_STATE.

uint16_t ble_ext_adv_mgr_get_adv_interval(uint8_t adv_handle)

Used to get current used maximum advertising interval.

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.

Return values:

0 -- Get the interval failed.
0x0020-0x4000 -- The current used maximum ADV interval.

Returns:

ADV interval.

void ble_ext_adv_print_info(void): Print ADV set information.

bool ble_ext_adv_is_ongoing(void)

Used to determine if LE advertising is ongoing.

Return values:

true -- LE advertising is ongoing.
false -- LE advertising is not ongoing.

Returns:

Operation result.

void ble_ext_adv_update_rpa_for_irk_changed(void)

When irk changed, rpa shall be updated.

Added Since 2.14.0.0:

Note

bool ble_ext_adv_get_rpa_by_adv_handle(uint8_t adv_handle, uint8_t *p_random_addr)

ble_ext_adv_get_rpa_by_adv_handle get rpa by adv handle

Added Since 2.13.0.0:

Note

Parameters:

adv_handle -- [in] LE ADV handle, each ADV set has an ADV handle.
p_random_addr -- [out] rpa find by adv handle.

Return values:

true -- return valid rpa
false -- not find valid rpa