nrf-softdevice-s132

Crates

git

Versions

default

Flavors

pub unsafe fn sd_ble_gap_scan_start(
p_scan_params: *const ble_gap_scan_params_t,
p_adv_report_buffer: *const ble_data_t
) -> u32
Expand description

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

@note The scanner will automatically stop in the following cases: - @ref sd_ble_gap_scan_stop is called. - @ref sd_ble_gap_connect is called. - A @ref BLE_GAP_EVT_TIMEOUT with source set to @ref BLE_GAP_TIMEOUT_SRC_SCAN is received. - When a @ref BLE_GAP_EVT_ADV_REPORT event is received and @ref ble_gap_adv_report_type_t::status is not set to @ref 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 @ref sd_ble_gap_scan_stop to stop scanning.

@note If a @ref BLE_GAP_EVT_ADV_REPORT event is received with @ref ble_gap_adv_report_type_t::status set to @ref 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 @event{@ref BLE_GAP_EVT_ADV_REPORT, An advertising or scan response packet has been received.} @event{@ref BLE_GAP_EVT_TIMEOUT, Scanner has timed out.} @endevents

@mscs @mmsc{@ref BLE_GAP_SCAN_MSC} @mmsc{@ref BLE_GAP_WL_SHARE_MSC} @endmscs

@param[in] p_scan_params Pointer to scan parameters structure. When this function is used to continue scanning, this parameter must be NULL. @param[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 @ref BLE_GAP_SCAN_BUFFER_SIZE for minimum and maximum buffer size. If the scanner receives advertising data larger than can be stored in the buffer, a @ref BLE_GAP_EVT_ADV_REPORT will be raised with @ref ble_gap_adv_report_type_t::status set to @ref BLE_GAP_ADV_DATA_STATUS_INCOMPLETE_TRUNCATED.

@retval ::NRF_SUCCESS Successfully initiated scanning procedure. @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. @retval ::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. @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. See @ref ble_gap_scan_params_t. @retval ::NRF_ERROR_NOT_SUPPORTED Unsupported parameters supplied. See @ref ble_gap_scan_params_t. @retval ::NRF_ERROR_INVALID_LENGTH The provided buffer length is invalid. See @ref BLE_GAP_SCAN_BUFFER_MIN. @retval ::NRF_ERROR_RESOURCES Not enough BLE role slots available. Stop one or more currently active roles (Central, Peripheral or Broadcaster) and try again @retval ::NRF_ERROR_NOT_SUPPORTED Unsupported PHYs supplied to the call.