GAP Privacy Exported Functions

group Gap_Privacy_Exported_Functions

Typedefs

typedef T_APP_RESULT (*P_FUN_PRIVACY_CB)(uint8_t msg_type, T_LE_PRIVACY_CB_DATA msg_data)

Callback for GAP to notify APP.

Param msg_type:

[in] Callback msg type.

Param msg_data:

[in] Message data T_LE_PRIVACY_CB_DATA.

Retval result:

T_APP_RESULT.

Return:

Result.

Functions

T_GAP_CAUSE le_privacy_set_param(T_LE_PRIVACY_PARAM_TYPE param, uint8_t len, void *p_value)

Set a LE privacy parameter.

This function can be called with a LE privacy parameter type T_LE_PRIVACY_PARAM_TYPE and it will set the privacy parameter. The 'p_value' field must point to an appropriate data type that meets the requirements for the corresponding parameter type. (For example, if required data length for parameter type is 2 octets, p_value should be cast to a pointer of uint16_t.)

Parameters:

  • param -- [in] LE privacy parameter type T_LE_PRIVACY_PARAM_TYPE.

  • len -- [in] Length of data to write.

  • p_value -- [in] Pointer to data to write.

Return values:

  • GAP_CAUSE_SUCCESS -- Operation success.

  • Others -- Operation failure.

Returns:

Operation result.

T_GAP_CAUSE le_privacy_get_param(T_LE_PRIVACY_PARAM_TYPE param, void *p_value)

Get an LE privacy parameter.

This function can be called with a LE privacy parameter type T_LE_PRIVACY_PARAM_TYPE and it will get the privacy parameter. The 'p_value' field must point to an appropriate data type that meets the requirements for the corresponding parameter type. (For example, if required data length for parameter type is 2 octets, p_value should be cast to a pointer of uint16_t.)

Parameters:

  • param -- [in] LE privacy parameter type T_LE_PRIVACY_PARAM_TYPE.

  • p_value -- [inout] Pointer to location to get the parameter value.

Return values:

  • GAP_CAUSE_SUCCESS -- Operation success.

  • Others -- Operation failure.

Returns:

Operation result.

void le_privacy_register_cb(P_FUN_PRIVACY_CB p_privacy_cb)

Register privacy callback to Bluetooth Host.

Parameters:

p_privacy_cb -- [in] Callback function provided by the APP to handle LE privacy messages sent from the Bluetooth Host.

  • NULL -> Not send GAP privacy messages to APP.

  • Other -> Use application-defined callback function.

T_GAP_CAUSE le_privacy_set_addr_resolution(bool enable)

Enable or disable LE privacy address resolution mode.

If sending request operation is successful, the enabling or disabling result will be returned by callback registered by le_privacy_register_cb with msg type GAP_MSG_LE_PRIVACY_RESOLUTION_STATUS_INFO.

Parameters:

enable -- [in] Enable or disable address resolution.

  • true: Enable address resolution.

  • false: Disable address resolution.

Return values:

  • GAP_CAUSE_SUCCESS -- Sending request operation is successful.

  • Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_privacy_read_peer_resolv_addr(T_GAP_IDENT_ADDR_TYPE peer_identity_address_type, uint8_t *peer_identity_address)

Read peer Resolvable Private Address.

If sending request operation is successful, the reading result will be returned by callback registered by le_privacy_register_cb with msg type GAP_MSG_LE_PRIVACY_READ_PEER_RESOLV_ADDR.

Parameters:

  • peer_identity_address_type -- [in] Peer identity address type T_GAP_IDENT_ADDR_TYPE.

  • peer_identity_address -- [in] Pointer to peer identity address.

Return values:

  • GAP_CAUSE_SUCCESS -- Sending request operation is successful.

  • Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_privacy_read_local_resolv_addr(T_GAP_IDENT_ADDR_TYPE peer_identity_address_type, uint8_t *peer_identity_address)

Read local Resolvable Private Address.

If sending request operation is successful, the reading result will be returned by callback registered by le_privacy_register_cb with msg type GAP_MSG_LE_PRIVACY_READ_LOCAL_RESOLV_ADDR.

Parameters:

  • peer_identity_address_type -- [in] Peer identity address type T_GAP_IDENT_ADDR_TYPE.

  • peer_identity_address -- [in] Pointer to peer identity address.

Return values:

  • GAP_CAUSE_SUCCESS -- Sending request operation is successful.

  • Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_privacy_set_resolv_priv_addr_timeout(void)

Set resolvable private address timeout with value set by le_privacy_set_param with parameter GAP_PARAM_PRIVACY_TIMEOUT.

If sending request operation is successful, the setting result will be returned by callback registered by le_privacy_register_cb with msg type GAP_MSG_LE_PRIVACY_SET_RESOLV_PRIV_ADDR_TIMEOUT.

Return values:

  • GAP_CAUSE_SUCCESS -- Sending request operation is successful.

  • Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_privacy_modify_resolv_list(T_GAP_RESOLV_LIST_OP operation, T_GAP_IDENT_ADDR_TYPE peer_identity_address_type, uint8_t *peer_identity_address)

Modify local resolving list.

When add device to local resolving list, APP shall select API based on the situation:

If sending request operation is successful, the modifying result will be returned by callback registered by le_privacy_register_cb with msg type GAP_MSG_LE_PRIVACY_MODIFY_RESOLV_LIST.

Parameters:
Return values:

  • GAP_CAUSE_SUCCESS -- Sending request operation is successful.

  • Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_privacy_add_resolv_list(T_GAP_IDENT_ADDR_TYPE peer_identity_address_type, uint8_t *peer_identity_address, uint8_t *peer_irk, bool use_local_irk)

Add device to local resolving list.

If sending request operation is successful, the adding result will be returned by callback registered by le_privacy_register_cb with msg type GAP_MSG_LE_PRIVACY_MODIFY_RESOLV_LIST.

Parameters:

  • peer_identity_address_type -- [in] Peer identity address type T_GAP_IDENT_ADDR_TYPE.

  • peer_identity_address -- [in] Pointer to peer identity address.

  • peer_irk -- [in] Pointer to peer IRK (16 octets).

    • NULL: No peer IRK, use all-zero IRK.

  • use_local_irk -- [in] Indicates whether local IRK has been distributed to the peer device.

    • false: Local IRK has not been distributed to the peer device.

    • true: Local IRK has been distributed to the peer device.

Return values:

  • GAP_CAUSE_SUCCESS -- Sending request operation is successful.

  • Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_privacy_set_mode(T_GAP_IDENT_ADDR_TYPE peer_identity_address_type, uint8_t *peer_identity_address, T_GAP_PRIVACY_MODE privacy_mode)

Set privacy mode.

If sending request operation is successful, the setting result will be returned by callback registered by le_privacy_register_cb with msg type GAP_MSG_LE_PRIVACY_SET_MODE.

Parameters:

  • peer_identity_address_type -- [in] Peer identity address type T_GAP_IDENT_ADDR_TYPE.

  • peer_identity_address -- [in] Pointer to peer identity address.

  • privacy_mode -- [in] Privacy mode T_GAP_PRIVACY_MODE.

Return values:

  • GAP_CAUSE_SUCCESS -- Sending request operation is successful.

  • Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_IDENT_ADDR_TYPE le_privacy_convert_addr_type(T_GAP_REMOTE_ADDR_TYPE type)

Convert remote Bluetooth device address type to identity address type.

Parameters:

type -- [in] Bluetooth device address type T_GAP_REMOTE_ADDR_TYPE.

Return values:

  • GAP_IDENT_ADDR_PUBLIC -- Public identity address.

  • GAP_IDENT_ADDR_RAND -- Random identity address.

Returns:

Identity address type T_GAP_IDENT_ADDR_TYPE.

bool le_privacy_check_resolvable_private_address(uint8_t *rpa, uint8_t *irk)

Check if a given Resolvable Private Address (RPA) can be resolved using a specified Identity Resolving Key (IRK).

This function determines if a provided Resolvable Private Address (RPA) associated with Bluetooth Low Energy (BLE) privacy mechanisms can be resolved using the specified Identity Resolving Key (IRK). It achieves this by utilizing encryption and comparison methods as defined in the Bluetooth specification for privacy address resolution.

Parameters:

  • rpa -- [in] Pointer to a 6-byte Resolvable Private Address that needs to be resolved. This address is typically a random address generated for privacy protection during BLE operations.

  • irk -- [in] Pointer to a 16-byte Identity Resolving Key used for resolving the Resolvable Private Address.

Return values:

  • true -- The Resolvable Private Address matches the IRK and successfully resolves. This indicates that the provided RPA is associated with the given IRK and should be accepted as a legitimate identity.

  • false -- The Resolvable Private Address does not match the IRK and fails to resolve. This means that the RPA is either not associated with the given IRK or could not be resolved, indicating it is not recognized as a valid identity with the provided key.

Returns:

Check result.