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