1 /* 2 * Copyright (c) 2017-2021 Nordic Semiconductor ASA 3 * Copyright (c) 2015-2016 Intel Corporation 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 #ifndef SUBSYS_BLUETOOTH_HOST_SCAN_H_ 9 #define SUBSYS_BLUETOOTH_HOST_SCAN_H_ 10 11 #include <stdint.h> 12 13 #include <zephyr/sys/atomic.h> 14 #include <zephyr/bluetooth/bluetooth.h> 15 16 /** 17 * Reasons why a scanner can be running. 18 * Used as input to @ref bt_le_scan_user_add 19 * and @ref bt_le_scan_user_remove. 20 */ 21 enum bt_le_scan_user { 22 /** The application explicitly instructed the stack to scan for advertisers 23 * using the API @ref bt_le_scan_start. 24 * Users of the scanner module may not use this flag as input to @ref bt_le_scan_user_add 25 * and @ref bt_le_scan_user_remove. Use ®ref bt_le_scan_start and @ref bt_le_scan_stop 26 * instead. 27 */ 28 BT_LE_SCAN_USER_EXPLICIT_SCAN, 29 30 /** 31 * Periodic sync syncing to a periodic advertiser. 32 */ 33 BT_LE_SCAN_USER_PER_SYNC, 34 35 /** 36 * Scanning to find devices to connect to. 37 */ 38 BT_LE_SCAN_USER_CONN, 39 40 /** 41 * Special state for a NOP for @ref bt_le_scan_user_add and @ref bt_le_scan_user_remove to 42 * not add/remove any user. 43 */ 44 BT_LE_SCAN_USER_NONE, 45 BT_LE_SCAN_USER_NUM_FLAGS, 46 }; 47 48 void bt_scan_reset(void); 49 50 bool bt_id_scan_random_addr_check(void); 51 bool bt_le_scan_active_scanner_running(void); 52 53 int bt_le_scan_set_enable(uint8_t enable); 54 55 void bt_periodic_sync_disable(void); 56 57 /** 58 * Start / update the scanner. 59 * 60 * This API updates the users of the scanner. 61 * Multiple users can be enabled at the same time. 62 * Depending on all the users, scan parameters are selected 63 * and the scanner is started or updated, if needed. 64 * This API may update the scan parameters, for example if the scanner is already running 65 * when another user that demands higher duty-cycle is being added. 66 * It is not allowed to add a user that was already added. 67 * 68 * Every SW module that informs the scanner that it should run, needs to eventually remove 69 * the flag again using @ref bt_le_scan_user_remove once it does not require 70 * the scanner to run, anymore. 71 * 72 * If flag is set to @ref BT_LE_SCAN_USER_NONE, no user is being added. Instead, the 73 * existing users are checked and the scanner is started, stopped or updated. 74 * For platforms where scanning and initiating at the same time is not supported, 75 * this allows the background scanner to be started or stopped once the device starts to 76 * initiate a connection. 77 * 78 * @param flag user requesting the scanner 79 * 80 * @retval 0 in case of success 81 * @retval -EALREADY if the user is already enabled 82 * @retval -EPERM if the explicit scanner is being enabled while the initiator is running 83 * and the device does not support this configuration. 84 * @retval -ENOBUFS if no hci command buffer could be allocated 85 * @retval -EBUSY if the scanner is updated in a different thread. The user was added but 86 * the scanner was not started/stopped/updated. 87 * @returns negative error codes for errors in @ref bt_hci_cmd_send_sync 88 */ 89 int bt_le_scan_user_add(enum bt_le_scan_user flag); 90 91 /** 92 * Stop / update the scanner. 93 * 94 * This API updates the users of the scanner. 95 * Depending on all enabled users, scan parameters are selected 96 * and the scanner is stopped or updated, if needed. 97 * This API may update the scan parameters, for example if the scanner is already running 98 * when a user that demands higher duty-cycle is being removed. 99 * Removing a user that was not added does not result in an error. 100 * 101 * This API allows removing the user why the scanner is running. 102 * If all users for the scanner to run are removed, this API will stop the scanner. 103 * 104 * If flag is set to @ref BT_LE_SCAN_USER_NONE, no user is being added. Instead, the 105 * existing users are checked and the scanner is started, stopped or updated. 106 * For platforms where scanning and initiating at the same time is not supported, 107 * this allows the background scanner to be started or stopped once the device starts to 108 * initiate a connection. 109 * 110 * @param flag user releasing the scanner 111 * 112 * @retval 0 in case of success 113 * @retval -ENOBUFS if no hci command buffer could be allocated 114 * @retval -EBUSY if the scanner is updated in a different thread. The user was removed but 115 * the scanner was not started/stopped/updated. 116 * @returns negative error codes for errors in @ref bt_hci_cmd_send_sync 117 */ 118 int bt_le_scan_user_remove(enum bt_le_scan_user flag); 119 120 /** 121 * Check if the explicit scanner was enabled. 122 */ 123 bool bt_le_explicit_scanner_running(void); 124 125 /** 126 * Check if an explicit scanner uses the same parameters 127 * 128 * @param create_param Parameters used for connection establishment. 129 * 130 * @return true If explicit scanner uses the same parameters 131 * @return false If explicit scanner uses different parameters 132 */ 133 bool bt_le_explicit_scanner_uses_same_params(const struct bt_conn_le_create_param *create_param); 134 #endif /* defined SUBSYS_BLUETOOTH_HOST_SCAN_H_ */ 135
