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
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. |