软件: nRF SKD Ver 15.2, S140 SoftDevice API
蓝牙 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 被释放。当扫描被停止,或这个功能被调用,且有另一个缓冲区, 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:
|
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).
Note
The buffer provided in sd_ble_gap_scan_start is released.
Relevant Message Sequence Charts
Scanning |
Whitelist Sharing |
Return values
NRF_SUCCESS | Successfully stopped scanning procedure. |
NRF_ERROR_INVALID_STATE | Not in the scanning state. |