nrf_ble_scan.h 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498
  1. /**
  2. * Copyright (c) 2018 - 2020, Nordic Semiconductor ASA
  3. *
  4. * All rights reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. * 1. Redistributions of source code must retain the above copyright notice, this
  10. * list of conditions and the following disclaimer.
  11. *
  12. * 2. Redistributions in binary form, except as embedded into a Nordic
  13. * Semiconductor ASA integrated circuit in a product or a software update for
  14. * such product, must reproduce the above copyright notice, this list of
  15. * conditions and the following disclaimer in the documentation and/or other
  16. * materials provided with the distribution.
  17. *
  18. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  19. * contributors may be used to endorse or promote products derived from this
  20. * software without specific prior written permission.
  21. *
  22. * 4. This software, with or without modification, must only be used with a
  23. * Nordic Semiconductor ASA integrated circuit.
  24. *
  25. * 5. Any software provided in binary form under this license must not be reverse
  26. * engineered, decompiled, modified and/or disassembled.
  27. *
  28. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  29. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  32. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  37. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38. *
  39. */
  40. /** @file
  41. *
  42. * @defgroup nrf_ble_scan Scanning Module
  43. * @{
  44. * @ingroup ble_sdk_lib
  45. * @brief Module for handling the BLE scanning.
  46. *
  47. * @details The Scanning Module handles the BLE scanning for your application.
  48. * The module offers several criteria for filtering the devices available for connection,
  49. * and it can also work in the simple mode without using the filtering.
  50. * If an event handler is provided, your main application can react to a filter match or to the need of setting the whitelist.
  51. * The module can also be configured to automatically
  52. * connect after it matches a filter or a device from the whitelist.
  53. *
  54. * @note The Scanning Module also supports applications with a multicentral link.
  55. */
  56. #ifndef NRF_BLE_SCAN_H__
  57. #define NRF_BLE_SCAN_H__
  58. #include <stdint.h>
  59. #include <stdbool.h>
  60. #include <string.h>
  61. #include "ble.h"
  62. #include "ble_gap.h"
  63. #include "app_util.h"
  64. #include "sdk_errors.h"
  65. #include "sdk_config.h"
  66. #ifdef __cplusplus
  67. extern "C" {
  68. #endif
  69. /**@defgroup NRF_BLE_SCAN_FILTER_MODE Filter modes
  70. * @{ */
  71. #define NRF_BLE_SCAN_NAME_FILTER (0x01) /**< Filters the device name. */
  72. #define NRF_BLE_SCAN_ADDR_FILTER (0x02) /**< Filters the device address. */
  73. #define NRF_BLE_SCAN_UUID_FILTER (0x04) /**< Filters the UUID. */
  74. #define NRF_BLE_SCAN_APPEARANCE_FILTER (0x08) /**< Filters the appearance. */
  75. #define NRF_BLE_SCAN_SHORT_NAME_FILTER (0x10) /**< Filters the device short name. */
  76. #define NRF_BLE_SCAN_ALL_FILTER (0x1F) /**< Uses the combination of all filters. */
  77. /* @} */
  78. /**@brief Macro for defining a nrf_ble_scan instance.
  79. *
  80. * @param _name Name of the instance.
  81. * @hideinitializer
  82. */
  83. #define NRF_BLE_SCAN_DEF(_name) \
  84. static nrf_ble_scan_t _name; \
  85. NRF_SDH_BLE_OBSERVER(_name ## _ble_obs, \
  86. NRF_BLE_SCAN_OBSERVER_PRIO, \
  87. nrf_ble_scan_on_ble_evt, &_name); \
  88. /**@brief Enumeration for scanning events.
  89. *
  90. * @details These events are propagated to the main application if a handler is provided during
  91. * the initialization of the Scanning Module. @ref NRF_BLE_SCAN_EVT_WHITELIST_REQUEST cannot be
  92. * ignored if whitelist is used.
  93. */
  94. typedef enum
  95. {
  96. NRF_BLE_SCAN_EVT_FILTER_MATCH, /**< A filter is matched or all filters are matched in the multifilter mode. */
  97. NRF_BLE_SCAN_EVT_WHITELIST_REQUEST, /**< Request the whitelist from the main application. For whitelist scanning to work, the whitelist must be set when this event occurs. */
  98. NRF_BLE_SCAN_EVT_WHITELIST_ADV_REPORT, /**< Send notification to the main application when a device from the whitelist is found. */
  99. NRF_BLE_SCAN_EVT_NOT_FOUND, /**< The filter was not matched for the scan data. */
  100. NRF_BLE_SCAN_EVT_SCAN_TIMEOUT, /**< Scan timeout. */
  101. NRF_BLE_SCAN_EVT_CONNECTING_ERROR, /**< Error occurred when establishing the connection. In this event, an error is passed from the function call @ref sd_ble_gap_connect. */
  102. NRF_BLE_SCAN_EVT_CONNECTED /**< Connected to device. */
  103. } nrf_ble_scan_evt_t;
  104. /**@brief Types of filters.
  105. */
  106. typedef enum
  107. {
  108. SCAN_NAME_FILTER, /**< Filter for names. */
  109. SCAN_SHORT_NAME_FILTER, /**< Filter for short names. */
  110. SCAN_ADDR_FILTER, /**< Filter for addresses. */
  111. SCAN_UUID_FILTER, /**< Filter for UUIDs. */
  112. SCAN_APPEARANCE_FILTER, /**< Filter for appearances. */
  113. } nrf_ble_scan_filter_type_t;
  114. typedef struct
  115. {
  116. char const * p_short_name; /**< Pointer to the short name. */
  117. uint8_t short_name_min_len; /**< Minimum length of the short name. */
  118. } nrf_ble_scan_short_name_t;
  119. /**@brief Structure for Scanning Module initialization.
  120. */
  121. typedef struct
  122. {
  123. ble_gap_scan_params_t const * p_scan_param; /**< BLE GAP scan parameters required to initialize the module. Can be initialized as NULL. If NULL, the parameters required to initialize the module are loaded from the static configuration. */
  124. bool connect_if_match; /**< If set to true, the module automatically connects after a filter match or successful identification of a device from the whitelist. */
  125. ble_gap_conn_params_t const * p_conn_param; /**< Connection parameters. Can be initialized as NULL. If NULL, the default static configuration is used. */
  126. uint8_t conn_cfg_tag; /**< Variable to keep track of what connection settings will be used if a filer match or a whitelist match results in a connection. */
  127. } nrf_ble_scan_init_t;
  128. /**@brief Structure for setting the filter status.
  129. *
  130. * @details This structure is used for sending filter status to the main application.
  131. */
  132. typedef struct
  133. {
  134. uint8_t name_filter_match : 1; /**< Set to 1 if name filter is matched. */
  135. uint8_t address_filter_match : 1; /**< Set to 1 if address filter is matched. */
  136. uint8_t uuid_filter_match : 1; /**< Set to 1 if uuid filter is matched. */
  137. uint8_t appearance_filter_match : 1; /**< Set to 1 if appearance filter is matched. */
  138. uint8_t short_name_filter_match : 1; /**< Set to 1 if short name filter is matched. */
  139. } nrf_ble_scan_filter_match;
  140. /**@brief Event structure for @ref NRF_BLE_SCAN_EVT_FILTER_MATCH.
  141. */
  142. typedef struct
  143. {
  144. ble_gap_evt_adv_report_t const * p_adv_report; /**< Event structure for @ref BLE_GAP_EVT_ADV_REPORT. This data allows the main application to establish connection. */
  145. nrf_ble_scan_filter_match filter_match; /**< Matching filters. Information about matched filters. */
  146. } nrf_ble_scan_evt_filter_match_t;
  147. /**@brief Event structure for @ref NRF_BLE_SCAN_EVT_CONNECTING_ERROR.
  148. */
  149. typedef struct
  150. {
  151. ret_code_t err_code; /**< Indicates success or failure of an API procedure. In case of failure, a comprehensive error code indicating the cause or reason for failure is provided. */
  152. } nrf_ble_scan_evt_connecting_err_t;
  153. /**@brief Event structure for @ref NRF_BLE_SCAN_EVT_CONNECTED.
  154. */
  155. typedef struct
  156. {
  157. ble_gap_evt_connected_t const * p_connected; /**< Connected event parameters. */
  158. uint16_t conn_handle; /**< Connection handle of the device on which the event occurred. */
  159. } nrf_ble_scan_evt_connected_t;
  160. /**@brief Structure for Scanning Module event data.
  161. *
  162. * @details This structure is used to send module event data to the main application when an event occurs.
  163. */
  164. typedef struct
  165. {
  166. nrf_ble_scan_evt_t scan_evt_id; /**< Type of event propagated to the main application. */
  167. union
  168. {
  169. nrf_ble_scan_evt_filter_match_t filter_match; /**< Scan filter match. */
  170. ble_gap_evt_timeout_t timeout; /**< Timeout event parameters. */
  171. ble_gap_evt_adv_report_t const * p_whitelist_adv_report; /**< Advertising report event parameters for whitelist. */
  172. ble_gap_evt_adv_report_t const * p_not_found; /**< Advertising report event parameters when filter is not found. */
  173. nrf_ble_scan_evt_connected_t connected; /**< Connected event parameters. */
  174. nrf_ble_scan_evt_connecting_err_t connecting_err; /**< Error event when connecting. Propagates the error code returned by the SoftDevice API @ref sd_ble_gap_scan_start. */
  175. } params;
  176. ble_gap_scan_params_t const * p_scan_params; /**< GAP scanning parameters. These parameters are needed to establish connection. */
  177. } scan_evt_t;
  178. /**@brief BLE scanning event handler type.
  179. */
  180. typedef void (*nrf_ble_scan_evt_handler_t)(scan_evt_t const * p_scan_evt);
  181. #if (NRF_BLE_SCAN_FILTER_ENABLE == 1)
  182. #if (NRF_BLE_SCAN_NAME_CNT > 0)
  183. typedef struct
  184. {
  185. char target_name[NRF_BLE_SCAN_NAME_CNT][NRF_BLE_SCAN_NAME_MAX_LEN]; /**< Names that the main application will scan for, and that will be advertised by the peripherals. */
  186. uint8_t name_cnt; /**< Name filter counter. */
  187. bool name_filter_enabled; /**< Flag to inform about enabling or disabling this filter. */
  188. } nrf_ble_scan_name_filter_t;
  189. #endif
  190. #if (NRF_BLE_SCAN_SHORT_NAME_CNT > 0)
  191. typedef struct
  192. {
  193. struct
  194. {
  195. char short_target_name[NRF_BLE_SCAN_SHORT_NAME_MAX_LEN]; /**< Short names that the main application will scan for, and that will be advertised by the peripherals. */
  196. uint8_t short_name_min_len; /**< Minimum length of the short name. */
  197. } short_name[NRF_BLE_SCAN_SHORT_NAME_CNT];
  198. uint8_t name_cnt; /**< Short name filter counter. */
  199. bool short_name_filter_enabled; /**< Flag to inform about enabling or disabling this filter. */
  200. } nrf_ble_scan_short_name_filter_t;
  201. #endif
  202. #if (NRF_BLE_SCAN_ADDRESS_CNT > 0)
  203. typedef struct
  204. {
  205. ble_gap_addr_t target_addr[NRF_BLE_SCAN_ADDRESS_CNT]; /**< Addresses in the same format as the format used by the SoftDevice that the main application will scan for, and that will be advertised by the peripherals. */
  206. uint8_t addr_cnt; /**< Address filter counter. */
  207. bool addr_filter_enabled; /**< Flag to inform about enabling or disabling this filter. */
  208. } nrf_ble_scan_addr_filter_t;
  209. #endif
  210. #if (NRF_BLE_SCAN_UUID_CNT > 0)
  211. typedef struct
  212. {
  213. ble_uuid_t uuid[NRF_BLE_SCAN_UUID_CNT]; /**< UUIDs that the main application will scan for, and that will be advertised by the peripherals. */
  214. uint8_t uuid_cnt; /**< UUID filter counter. */
  215. bool uuid_filter_enabled; /**< Flag to inform about enabling or disabling this filter. */
  216. } nrf_ble_scan_uuid_filter_t;
  217. #endif
  218. #if (NRF_BLE_SCAN_APPEARANCE_CNT > 0)
  219. typedef struct
  220. {
  221. uint16_t appearance[NRF_BLE_SCAN_APPEARANCE_CNT]; /**< Apperances that the main application will scan for, and that will be advertised by the peripherals. */
  222. uint8_t appearance_cnt; /**< Appearance filter counter. */
  223. bool appearance_filter_enabled; /**< Flag to inform about enabling or disabling this filter. */
  224. } nrf_ble_scan_appearance_filter_t;
  225. #endif
  226. /**@brief Filters data.
  227. *
  228. * @details This structure contains all filter data and the information about enabling and disabling any type of filters.
  229. * Flag all_filter_mode informs about the filter mode. If this flag is set, then all types of enabled
  230. * filters must be matched for the module to send a notification to the main application. Otherwise, it is enough to match
  231. * one of filters to send notification.
  232. */
  233. typedef struct
  234. {
  235. #if (NRF_BLE_SCAN_NAME_CNT > 0)
  236. nrf_ble_scan_name_filter_t name_filter; /**< Name filter data. */
  237. #endif
  238. #if (NRF_BLE_SCAN_SHORT_NAME_CNT > 0)
  239. nrf_ble_scan_short_name_filter_t short_name_filter; /**< Short name filter data. */
  240. #endif
  241. #if (NRF_BLE_SCAN_ADDRESS_CNT > 0)
  242. nrf_ble_scan_addr_filter_t addr_filter; /**< Address filter data. */
  243. #endif
  244. #if (NRF_BLE_SCAN_UUID_CNT > 0)
  245. nrf_ble_scan_uuid_filter_t uuid_filter; /**< UUID filter data. */
  246. #endif
  247. #if (NRF_BLE_SCAN_APPEARANCE_CNT > 0)
  248. nrf_ble_scan_appearance_filter_t appearance_filter; /**< Appearance filter data. */
  249. #endif
  250. bool all_filters_mode; /**< Filter mode. If true, all set filters must be matched to generate an event.*/
  251. } nrf_ble_scan_filters_t;
  252. #endif // NRF_BLE_SCAN_FILTER_ENABLE
  253. /**@brief Scan module instance. Options for the different scanning modes.
  254. *
  255. * @details This structure stores all module settings. It is used to enable or disable scanning modes
  256. * and to configure filters.
  257. */
  258. typedef struct
  259. {
  260. #if (NRF_BLE_SCAN_FILTER_ENABLE == 1)
  261. nrf_ble_scan_filters_t scan_filters; /**< Filter data. */
  262. #endif
  263. bool connect_if_match; /**< If set to true, the module automatically connects after a filter match or successful identification of a device from the whitelist. */
  264. ble_gap_conn_params_t conn_params; /**< Connection parameters. */
  265. uint8_t conn_cfg_tag; /**< Variable to keep track of what connection settings will be used if a filer match or a whitelist match results in a connection. */
  266. ble_gap_scan_params_t scan_params; /**< GAP scanning parameters. */
  267. nrf_ble_scan_evt_handler_t evt_handler; /**< Handler for the scanning events. Can be initialized as NULL if no handling is implemented in the main application. */
  268. uint8_t scan_buffer_data[NRF_BLE_SCAN_BUFFER]; /**< Buffer where advertising reports will be stored by the SoftDevice. */
  269. ble_data_t scan_buffer; /**< Structure-stored pointer to the buffer where advertising reports will be stored by the SoftDevice. */
  270. } nrf_ble_scan_t;
  271. /**@brief Function for indicating that the Scanning Module is using the whitelist.
  272. *
  273. * @param[in] p_scan_ctx Pointer to the Scanning Module instance.
  274. *
  275. * @return Whether the whitelist is used.
  276. */
  277. bool is_whitelist_used(nrf_ble_scan_t const * const p_scan_ctx);
  278. /**@brief Function for initializing the Scanning Module.
  279. *
  280. * @param[out] p_scan_ctx Pointer to the Scanning Module instance. This structure must be supplied by
  281. * the application. It is initialized by this function and is later used
  282. * to identify this particular module instance.
  283. *
  284. * @param[in] p_init Can be initialized as NULL. If NULL, the parameters required to initialize
  285. * the module are loaded from static configuration.
  286. * If module is to establish the connection automatically, this must be initialized
  287. * with the relevant data.
  288. * @param[in] evt_handler Handler for the scanning events.
  289. * Can be initialized as NULL if no handling is implemented in the main application.
  290. *
  291. * @retval NRF_SUCCESS If initialization was successful.
  292. * @retval NRF_ERROR_NULL When the NULL pointer is passed as input.
  293. */
  294. ret_code_t nrf_ble_scan_init(nrf_ble_scan_t * const p_scan_ctx,
  295. nrf_ble_scan_init_t const * const p_init,
  296. nrf_ble_scan_evt_handler_t evt_handler);
  297. /**@brief Function for starting scanning.
  298. *
  299. * @details This function starts the scanning according to the configuration set during the initialization.
  300. *
  301. * @param[in] p_scan_ctx Pointer to the Scanning Module instance.
  302. *
  303. * @retval NRF_SUCCESS If scanning started. Otherwise, an error code is returned.
  304. * @retval NRF_ERROR_NULL If NULL pointer is passed as input.
  305. *
  306. * @return This API propagates the error code returned by the
  307. * SoftDevice API @ref sd_ble_gap_scan_start.
  308. */
  309. ret_code_t nrf_ble_scan_start(nrf_ble_scan_t const * const p_scan_ctx);
  310. /**@brief Function for stopping scanning.
  311. */
  312. void nrf_ble_scan_stop(void);
  313. #if (NRF_BLE_SCAN_FILTER_ENABLE == 1)
  314. /**@brief Function for enabling filtering.
  315. *
  316. * @details The filters can be combined with each other. For example, you can enable one filter or several filters.
  317. * For example, (NRF_BLE_SCAN_NAME_FILTER | NRF_BLE_SCAN_UUID_FILTER) enables UUID and name filters.
  318. *
  319. * @param[in] mode Filter mode: @ref NRF_BLE_SCAN_FILTER_MODE.
  320. * @param[in] match_all If this flag is set, all types of enabled filters must be matched
  321. * before generating @ref NRF_BLE_SCAN_EVT_FILTER_MATCH to the main application. Otherwise, it is enough to match
  322. * one filter to trigger the filter match event.
  323. * @param[in] p_scan_ctx Pointer to the Scanning Module instance.
  324. *
  325. * @retval NRF_SUCCESS If the filters are enabled successfully.
  326. * @retval NRF_ERROR_INVALID_PARAM If the filter mode is incorrect. Available filter modes: @ref NRF_BLE_SCAN_FILTER_MODE.
  327. * @retval NRF_ERROR_NULL If a NULL pointer is passed as input.
  328. */
  329. ret_code_t nrf_ble_scan_filters_enable(nrf_ble_scan_t * const p_scan_ctx,
  330. uint8_t mode,
  331. bool match_all);
  332. /**@brief Function for disabling filtering.
  333. *
  334. * @details This function disables all filters.
  335. * Even if the automatic connection establishing is enabled,
  336. * the connection will not be established with the first
  337. device found after this function is called.
  338. *
  339. * @param[in] p_scan_ctx Pointer to the Scanning Module instance.
  340. *
  341. * @retval NRF_SUCCESS If filters are disabled successfully.
  342. * @retval NRF_ERROR_NULL If a NULL pointer is passed as input.
  343. */
  344. ret_code_t nrf_ble_scan_filters_disable(nrf_ble_scan_t * const p_scan_ctx);
  345. /**@brief Function for getting filter status.
  346. *
  347. * @details This function returns the filter setting and whether it is enabled or disabled.
  348. * @param[out] p_status Filter status.
  349. * @param[in] p_scan_ctx Pointer to the Scanning Module instance.
  350. *
  351. * @retval NRF_SUCCESS If filter status is returned.
  352. * @retval NRF_ERROR_NULL If a NULL pointer is passed as input.
  353. */
  354. ret_code_t nrf_ble_scan_filter_get(nrf_ble_scan_t * const p_scan_ctx,
  355. nrf_ble_scan_filters_t * p_status);
  356. /**@brief Function for adding any type of filter to the scanning.
  357. *
  358. * @details This function adds a new filter by type @ref nrf_ble_scan_filter_type_t.
  359. * The filter will be added if the number of filters of a given type does not exceed @ref NRF_BLE_SCAN_UUID_CNT,
  360. * @ref NRF_BLE_SCAN_NAME_CNT, @ref NRF_BLE_SCAN_ADDRESS_CNT, or @ref NRF_BLE_SCAN_APPEARANCE_CNT, depending on the filter type,
  361. * and if the same filter has not already been set.
  362. *
  363. * @param[in,out] p_scan_ctx Pointer to the Scanning Module instance.
  364. * @param[in] type Filter type.
  365. * @param[in] p_data The filter data to add.
  366. *
  367. * @retval NRF_SUCCESS If the filter is added successfully.
  368. * @retval NRF_ERROR_NULL If a NULL pointer is passed as input.
  369. * @retval NRF_ERROR_DATA_SIZE If the name filter length is too long. Maximum name filter length corresponds to @ref NRF_BLE_SCAN_NAME_MAX_LEN.
  370. * @retval NRF_ERROR_NO_MEMORY If the number of available filters is exceeded.
  371. * @retval NRF_ERROR_INVALID_PARAM If the filter type is incorrect. Available filter types: @ref nrf_ble_scan_filter_type_t.
  372. * @retval BLE_ERROR_GAP_INVALID_BLE_ADDR If the BLE address type is invalid.
  373. */
  374. ret_code_t nrf_ble_scan_filter_set(nrf_ble_scan_t * const p_scan_ctx,
  375. nrf_ble_scan_filter_type_t type,
  376. void const * p_data);
  377. /**@brief Function for removing all set filters.
  378. *
  379. * @details The function removes all previously set filters.
  380. *
  381. * @note After using this function the filters are still enabled.
  382. *
  383. * @param[in,out] p_scan_ctx Pointer to the Scanning Module instance.
  384. *
  385. * @retval NRF_SUCCESS If all filters are removed successfully.
  386. */
  387. ret_code_t nrf_ble_scan_all_filter_remove(nrf_ble_scan_t * const p_scan_ctx);
  388. #endif // NRF_BLE_SCAN_FILTER_ENABLE
  389. /**@brief Function for changing the scanning parameters.
  390. *
  391. **@details Use this function to change scanning parameters. During the parameter change
  392. * the scan is stopped. To resume scanning, use @ref nrf_ble_scan_start.
  393. * Scanning parameters can be set to NULL. If so, the default static configuration
  394. * is used. For example, use this function when the @ref NRF_BLE_SCAN_EVT_WHITELIST_ADV_REPORT event is generated.
  395. * The generation of this event means that there is a risk that the whitelist is empty. In such case, this function can change
  396. * the scanning parameters, so that the whitelist is not used, and you avoid the error caused by scanning with the whitelist
  397. * when there are no devices on the whitelist.
  398. *
  399. * @param[in,out] p_scan_ctx Pointer to the Scanning Module instance.
  400. * @param[in] p_scan_param GAP scanning parameters. Can be initialized as NULL.
  401. *
  402. * @retval NRF_SUCCESS If parameters are changed successfully.
  403. * @retval NRF_ERROR_NULL If a NULL pointer is passed as input.
  404. */
  405. ret_code_t nrf_ble_scan_params_set(nrf_ble_scan_t * const p_scan_ctx,
  406. ble_gap_scan_params_t const * p_scan_param);
  407. /**@brief Function for handling the BLE stack events of the application.
  408. *
  409. * @param[in] p_ble_evt Pointer to the BLE event received.
  410. * @param[in,out] p_scan Pointer to the Scanning Module instance.
  411. */
  412. void nrf_ble_scan_on_ble_evt(ble_evt_t const * p_ble_evt, void * p_scan);
  413. /**@brief Function for converting the raw address to the SoftDevice GAP address.
  414. *
  415. * @details This function inverts the byte order in the address. If you enter the address as it is displayed
  416. * (for example, on a phone screen from left to right), you must use this function to
  417. * convert the address to the SoftDevice address type.
  418. *
  419. * @param[in] addr Address to be converted to the SoftDevice address.
  420. * @param[out] p_gap_addr The Bluetooth Low Energy address.
  421. *
  422. * @retval BLE_ERROR_GAP_INVALID_BLE_ADDR If the BLE address type is invalid.
  423. * @retval NRF_SUCCESS If the address is copied and converted successfully.
  424. */
  425. ret_code_t nrf_ble_scan_copy_addr_to_sd_gap_addr(ble_gap_addr_t * p_gap_addr,
  426. uint8_t const addr[BLE_GAP_ADDR_LEN]);
  427. #ifdef __cplusplus
  428. }
  429. #endif
  430. #endif // NRF_BLE_SCAN_H__
  431. /** @} */