Bluetooth LE API provides functions for bluetooth extended advertising functionality such as setting Primary and Secondary Phy.

Required Header

#include <bluetooth.h>

Overview

The Bluetooth Adapter LE APIs provide several functions to enhance the LE experience. These include starting a new LE scan session, adjusting the LE scan role, selecting the preferred LE scan physical layer, enabling or disabling LE advertising legacy mode, specifying the primary and secondary LE advertising physical layers, confirming LE Extended Advertising and Extended Scan support availability, obtaining the maximum allowed advertising data length, accessing primary and secondary LE physical layer data from extended scan results, retrieving advertising SID values, periodic advertising intervals, determining whether a scan result is considered "extended", and fetching legacy scan result information from extended scan results. These features cater to diverse needs while ensuring efficient utilization of LE resources.

Related Features

This API is related with the following features:

http://tizen.org/feature/network.bluetooth
http://tizen.org/feature/network.bluetooth.le
http://tizen.org/feature/network.bluetooth.le.5_0
http://tizen.org/feature/network.bluetooth.le.adv_ext
It is recommended to design applications with regard to features, for reliability.

You can check if the device supports the related features for this API by using System Information, and control your application's actions accordingly.

To ensure your application is only running on devices with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from feature element description.

Functions
int	bt_adapter_le_start_scan_new (bt_adapter_le_new_scan_result_cb cb, void *user_data)
	Starts the LE scan to find LE advertisement.
int	bt_adapter_le_set_scan_role (bt_adapter_le_scan_role_e role)
	Sets Bluetooth LE scan role.
int	bt_adapter_le_set_scan_phy (bt_adapter_le_phy_e phy)
	Sets Bluetooth LE scan phy.
int	bt_adapter_le_set_advertising_legacy_mode (bt_advertiser_h advertiser, bool is_legacy)
	Sets Bluetooth LE advertising legacy mode.
int	bt_adapter_le_set_advertising_primary_phy (bt_advertiser_h advertiser, bt_adapter_le_phy_e primary_phy)
	Sets Bluetooth LE advertising primary phy.
int	bt_adapter_le_set_advertising_secondary_phy (bt_advertiser_h advertiser, bt_adapter_le_phy_e secondary_phy)
	Sets Bluetooth LE advertising secondary phy.
int	bt_adapter_le_is_extended_advertising_supported (bool *is_supported)
	Checks if LE Extended Advertising feature is supported or not.
int	bt_adapter_le_is_extended_scan_supported (bool *is_supported)
	Checks if LE Extended Scan feature is supported or not.
int	bt_adapter_le_get_maximum_advertising_data_length (int *data_length)
	Gets maximum advertisement data length supported by controller.
int	bt_adapter_le_get_new_scan_result_primary_phy (bt_new_scan_result_h handle, int *primary_phy)
	Gets the primary phy data from the extended scan result.
int	bt_adapter_le_get_new_scan_result_secondary_phy (bt_new_scan_result_h handle, int *secondary_phy)
	Gets the secondary phy data from the extended scan result.
int	bt_adapter_le_get_new_scan_result_advertising_sid (bt_new_scan_result_h handle, int *advertising_sid)
	Gets the advertising sid data from the extended scan result.
int	bt_adapter_le_get_new_scan_result_periodic_adv_int (bt_new_scan_result_h handle, int *periodic_adv_int)
	Gets the periodic advertising interval data from the extended scan result.
int	bt_adapter_le_get_new_scan_result_is_extended (bt_new_scan_result_h handle, bool *is_extended)
	Checks if the scan result is extended or not.
int	bt_adapter_le_get_new_scan_result_legacy_info (bt_new_scan_result_h handle, bt_adapter_le_device_scan_result_info_s **legacy_info)
	Gets the legacy scan result information from the extended scan result.
Typedefs
typedef void *	bt_new_scan_result_h
	The handle of a new scan result.
typedef void(*	bt_adapter_le_new_scan_result_cb )(int result, bt_new_scan_result_h handle, void *user_data)
	Called when the LE advertisement has been found.

Typedef Documentation

typedef void(* bt_adapter_le_new_scan_result_cb)(int result, bt_new_scan_result_h handle, void *user_data)

Called when the LE advertisement has been found.

Since :: 8.0

Parameters:

[in]	result	The result of the LE scan
[in]	handle	The handle of a new scan result
[in]	user_data	The user data passed from the start function

See also:: bt_adapter_le_start_scan_new()

typedef void* bt_new_scan_result_h

The handle of a new scan result.

Since :: 8.0

Enumeration Type Documentation

enum bt_adapter_le_phy_e

Enumerations of the Bluetooth LE phy.

Since :: 8.0

Enumerator:

BT_LE_ALL_PHY	All phy
BT_LE_1M_PHY	1M phy
BT_LE_2M_PHY	2M phy
BT_LE_CODED_PHY	Coded phy

enum bt_adapter_le_scan_role_e

Enumerations of the Bluetooth LE scan role.

Since :: 8.0

Enumerator:

BT_ADAPTER_LE_SCAN_ALL	Scan all
BT_ADAPTER_LE_SCAN_LEGACY_ONLY	Legacy scan only
BT_ADAPTER_LE_SCAN_EXTENDED_ONLY	Extended scan only

Function Documentation

int bt_adapter_le_get_maximum_advertising_data_length ( int * data_length )

Gets maximum advertisement data length supported by controller.

Since :: 8.0

Remarks:: The LE Maximum Advertising Data Length feature was introduced in the BT 5.0 core specification.

Parameters:

[out] data_length The maximum length supported by controller for use as advertisement data or scan response data

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Adapter is not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

Precondition:: The state of local Bluetooth must be BT_ADAPTER_ENABLED.

int bt_adapter_le_get_new_scan_result_advertising_sid	(	bt_new_scan_result_h	handle,
		int *	advertising_sid
	)

Gets the advertising sid data from the extended scan result.

Since :: 8.0

Parameters:

[in]	handle	The extended scan result handle
[out]	advertising_sid	The advertising sid

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed

See also:: bt_adapter_le_start_scan_new(); bt_adapter_le_new_scan_result_cb()

int bt_adapter_le_get_new_scan_result_is_extended	(	bt_new_scan_result_h	handle,
		bool *	is_extended
	)

Checks if the scan result is extended or not.

Since :: 8.0

Parameters:

[in]	handle	The extended scan result handle
[out]	is_extended	The whether to extended

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed

See also:: bt_adapter_le_start_scan_new(); bt_adapter_le_new_scan_result_cb()

int bt_adapter_le_get_new_scan_result_legacy_info	(	bt_new_scan_result_h	handle,
		bt_adapter_le_device_scan_result_info_s **	legacy_info
	)

Gets the legacy scan result information from the extended scan result.

Since :: 8.0

Remarks:: The legacy_info should not be released.; The legacy_info is available until the callback has been called.

Parameters:

[in]	handle	The extended scan result handle
[out]	legacy_info	The legacy scan result information

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed

See also:: bt_adapter_le_start_scan_new(); bt_adapter_le_new_scan_result_cb()

int bt_adapter_le_get_new_scan_result_periodic_adv_int	(	bt_new_scan_result_h	handle,
		int *	periodic_adv_int
	)

Gets the periodic advertising interval data from the extended scan result.

Since :: 8.0

Parameters:

[in]	handle	The extended scan result handle
[out]	periodic_adv_int	The periodic advertising interval

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed

See also:: bt_adapter_le_start_scan_new(); bt_adapter_le_new_scan_result_cb()

int bt_adapter_le_get_new_scan_result_primary_phy	(	bt_new_scan_result_h	handle,
		int *	primary_phy
	)

Gets the primary phy data from the extended scan result.

Since :: 8.0

Parameters:

[in]	handle	The extended scan result handle
[out]	primary_phy	The primary PHY

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed

See also:: bt_adapter_le_start_scan_new(); bt_adapter_le_new_scan_result_cb()

int bt_adapter_le_get_new_scan_result_secondary_phy	(	bt_new_scan_result_h	handle,
		int *	secondary_phy
	)

Gets the secondary phy data from the extended scan result.

Since :: 8.0

Parameters:

[in]	handle	The extended scan result handle
[out]	secondary_phy	The secondary PHY

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed

See also:: bt_adapter_le_start_scan_new(); bt_adapter_le_new_scan_result_cb()

int bt_adapter_le_is_extended_advertising_supported ( bool * is_supported )

Checks if LE Extended Advertising feature is supported or not.

Since :: 8.0

Remarks:: The LE Extended Advertising feature was introduced in the BT 5.0 core specification.

Parameters:

[out] is_supported The LE Extended Advertising feature support: (true = supported , false = not supported)

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Adapter is not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

Precondition:: The state of local Bluetooth must be BT_ADAPTER_ENABLED.

int bt_adapter_le_is_extended_scan_supported ( bool * is_supported )

Checks if LE Extended Scan feature is supported or not.

Since :: 8.0

Remarks:: The LE Extended Scan feature was introduced in the BT 5.0 core specification.

Parameters:

[out] is_supported The LE Extended Scan feature support: (true = supported , false = not supported)

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Adapter is not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

Precondition:: The state of local Bluetooth must be BT_ADAPTER_ENABLED.

int bt_adapter_le_set_advertising_legacy_mode	(	bt_advertiser_h	advertiser,
		bool	is_legacy
	)

Sets Bluetooth LE advertising legacy mode.

Since :: 8.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	advertiser	The handle of advertiser
[in]	is_legacy	Advertisement is extended or legacy

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Adapter is not enabled

Precondition:: The state of local bluetooth must be BT_ADAPTER_ENABLED.; The bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize()

int bt_adapter_le_set_advertising_primary_phy	(	bt_advertiser_h	advertiser,
		bt_adapter_le_phy_e	primary_phy
	)

Sets Bluetooth LE advertising primary phy.

Since :: 8.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	advertiser	The handle of advertiser
[in]	primary_phy	Primary phy of advertiser. Valid values are BT_LE_1M_PHY, BT_LE_CODED_PHY.

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Adapter is not enabled

Precondition:: The state of local bluetooth must be BT_ADAPTER_ENABLED.; The bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize()

int bt_adapter_le_set_advertising_secondary_phy	(	bt_advertiser_h	advertiser,
		bt_adapter_le_phy_e	secondary_phy
	)

Sets Bluetooth LE advertising secondary phy.

Since :: 8.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	advertiser	The handle of advertiser
[in]	secondary_phy	Secondary phy of advertiser, Valid values are BT_LE_1M_PHY, BT_LE_2M_PHY, BT_LE_CODED_PHY.

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Adapter is not enabled

Precondition:: The state of local bluetooth must be BT_ADAPTER_ENABLED.; The bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize()

int bt_adapter_le_set_scan_phy ( bt_adapter_le_phy_e phy )

Sets Bluetooth LE scan phy.

Since :: 8.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in] phy The scanning phy. Valid values are one of BT_LE_ALL_PHY, BT_LE_1M_PHY, BT_LE_CODED_PHY.

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Adapter is not enabled

Precondition:: The state of local bluetooth must be BT_ADAPTER_ENABLED.; The bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize()

int bt_adapter_le_set_scan_role ( bt_adapter_le_scan_role_e role )

Sets Bluetooth LE scan role.

Since :: 8.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in] role The scan role

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Adapter is not enabled

Precondition:: The state of local bluetooth must be BT_ADAPTER_ENABLED.; The bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize()

int bt_adapter_le_start_scan_new	(	bt_adapter_le_new_scan_result_cb	cb,
		void *	user_data
	)

Starts the LE scan to find LE advertisement.

If a LE advertisement is found, bt_adapter_le_new_scan_result_cb() will be invoked.

Since :: 8.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	cb	The callback to report the result of this function
[in]	user_data	The user data to be passed when callback is called

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_NOW_IN_PROGRESS	Operation is now in progress
BT_ERROR_OPERATION_FAILED	Operation failed

Precondition:: The state of local Bluetooth must be BT_ADAPTER_ENABLED.

Postcondition:: This function invokes bt_adapter_le_scan_result_cb().

See also:: bt_adapter_le_new_scan_result_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation