Nordic nRF5 SDK 学习笔记之九, 蓝牙 Central 扫描函数 sd_ble_gap_scan_start() 理解

软件: nRF SKD Ver 15.2

蓝牙 Central 扫描函数

uint32_t sd_ble_gap_scan_start (ble_gap_scan_params_t const * p_scan_params,ble_data_t const * p_adv_report_buffer)

开始或连续扫描 ( GAP 发现进程, 观察进程 )

注意:

调用函数 sd_ble_gap_scan_start() 时，需要应用通过的 p_adv_report_buffer 保持 memory pointed, 直到 p_adv_report_buffer 被释放。当扫描被停止，或这个功能被调用，且有另一个缓冲区.

在下列情况，扫描将被自动停止.

* sd_ble_gap_scan_stop() 函数被调用

* sd_ble_gap_connect() 数被调用

* BLE_GAP_EVT_TIMEOUT被设置，且 BLE_GAP_TIMEOUT_SRC_SCAN 事件出现

* BLE_GAP_EVT_ADV_REPORT 事件出现，且 ble_gap_adv_report_type_t::status 没有被设置为 BLE_GAP_ADV_DATA_STATUS_INCOMPLETE_MORE_DATA；此条件下，扫描是被暂停，以便应用获取接收到的数据。应用需调用继续扫描，或是调用 sd_ble_gap_scan_stop() 来停止扫描。

BLE_GAP_EVT_ADV_REPORT 事件出现，且 ble_gap_adv_report_type_t::status 被设置为 BLE_GAP_ADV_DATA_STATUS_INCOMPLETE_MORE_DATA；此条件下，扫描继续进行，应用将从广播事件中获取更多报告。这些报告将包括旧的和新的接收到数据。

NORDIC 官方原文:

uint32_t sd_ble_gap_scan_start	(	ble_gap_scan_params_t const *	p_scan_params,
		ble_data_t const *	p_adv_report_buffer
	)

Start or continue scanning (GAP Discovery procedure, Observer Procedure).

Note

A call to this function will require the application to keep the memory pointed by p_adv_report_buffer alive until the buffer is released. The buffer is released when the scanner is stopped or when this function is called with another buffer.

The scanner will automatically stop in the following cases:

sd_ble_gap_scan_stop is called.
sd_ble_gap_connect is called.
A BLE_GAP_EVT_TIMEOUT with source set to BLE_GAP_TIMEOUT_SRC_SCAN is received.
When a BLE_GAP_EVT_ADV_REPORT event is received and ble_gap_adv_report_type_t::status is not set to BLE_GAP_ADV_DATA_STATUS_INCOMPLETE_MORE_DATA. In this case scanning is only paused to let the application access received data. The application must call this function to continue scanning, or call sd_ble_gap_scan_stop to stop scanning.

If a BLE_GAP_EVT_ADV_REPORT event is received with ble_gap_adv_report_type_t::status set to BLE_GAP_ADV_DATA_STATUS_INCOMPLETE_MORE_DATA, the scanner will continue scanning, and the application will receive more reports from this advertising event. The following reports will include the old and new received data.

Events generated

BLE_GAP_EVT_ADV_REPORT	An advertising or scan response packet has been received.
BLE_GAP_EVT_TIMEOUT	Scanner has timed out.

Relevant Message Sequence Charts

Scanning

Whitelist Sharing

Parameters

[in]	p_scan_params	Pointer to scan parameters structure. When this function is used to continue scanning, this parameter must be NULL.
[in]	p_adv_report_buffer	Pointer to buffer used to store incoming advertising data. The memory pointed to should be kept alive until the scanning is stopped. See GAP Minimum scanner buffer size for minimum and maximum buffer size. If the scanner receives advertising data larger than can be stored in the buffer, a BLE_GAP_EVT_ADV_REPORT will be raised with ble_gap_adv_report_type_t::status set to BLE_GAP_ADV_DATA_STATUS_INCOMPLETE_TRUNCATED.

Return values

NRF_SUCCESS	Successfully initiated scanning procedure.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_STATE	Invalid state to perform operation. Either: Scanning is already ongoing and p_scan_params was not NULL Scanning is not running and p_scan_params was NULL. The scanner has timed out when this function is called to continue scanning.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied. See ble_gap_scan_params_t.
NRF_ERROR_NOT_SUPPORTED	Unsupported parameters supplied. See ble_gap_scan_params_t.
NRF_ERROR_INVALID_LENGTH	The provided buffer length is invalid. See BLE_GAP_SCAN_BUFFER_MIN.
NRF_ERROR_RESOURCES	Not enough BLE role slots available. Stop one or more currently active roles (Central, Peripheral or Broadcaster) and try again

uint32_t sd_ble_gap_scan_stop

(

void

)

Stop scanning (GAP Discovery procedure, Observer Procedure).