1 /***************************************************************************//**
2  * @brief Bluetooth controller callback API
3  *******************************************************************************
4  * # License
5  * <b>Copyright 2023 Silicon Laboratories Inc. www.silabs.com</b>
6  *******************************************************************************
7  *
8  * SPDX-License-Identifier: Zlib
9  *
10  * The licensor of this software is Silicon Laboratories Inc.
11  *
12  * This software is provided 'as-is', without any express or implied
13  * warranty. In no event will the authors be held liable for any damages
14  * arising from the use of this software.
15  *
16  * Permission is granted to anyone to use this software for any purpose,
17  * including commercial applications, and to alter it and redistribute it
18  * freely, subject to the following restrictions:
19  *
20  * 1. The origin of this software must not be misrepresented; you must not
21  *    claim that you wrote the original software. If you use this software
22  *    in a product, an acknowledgment in the product documentation would be
23  *    appreciated but is not required.
24  * 2. Altered source versions must be plainly marked as such, and must not be
25  *    misrepresented as being the original software.
26  * 3. This notice may not be removed or altered from any source distribution.
27  *
28  ******************************************************************************/
29 
30 #ifndef SL_BTCTRL_EVENTS_H
31 #define SL_BTCTRL_EVENTS_H
32 
33 #include <stdbool.h>
34 #include "sl_btctrl_packets.h"
35 
36 /**
37  * @addtogroup sl_btctrl_callbacks Bluetooth Controller Callbacks
38  *
39  * This API can be used to change the behaviour of Bluetooth controller.
40  *
41  * Example usage: RSSI based scan request transmission can be implented by
42  * adding following callback function into application code. Following
43  * examples adds logic to transmit scan request packet only to the devices
44  * which advertising packet RSSI is over -60.
45  *
46  * \code{.c}
47  *  #include <sl_btctrl_callbacks.h>
48  *  #include <sl_btctrl_packets.h>
49  *
50  *  bool sl_btctrl_filter_scan_request_transmission_cb(sl_btctrl_packet_t packet)
51  *  {
52  *    int8_t rssi = sl_btctrl_get_packet_rssi(packet);
53  *    return rssi > -60;
54  *  }
55  * \endcode
56  *
57  * \note All callback functions are called from critical section which
58  *       means that they should return immediately and should not do any
59  *       time consuming operations.
60  *
61  * \note It is NOT allowed to
62  *         - call more that few instructions, which consume less than one micro second
63  *         - call any BGAPI functions or other time consuming operations
64  *
65  * \note Only APIs from sl_btctrl_packets.h can be used in callback functions.
66  * @{
67  */
68 
69 /**
70  * This callback function is called before scan request transmission. The
71  * return value of callback function is used as a guidance for controller
72  * to decide whether or not to transmit scan request packet.
73  *
74  * @param packet Received advertising packet from peripheral.
75  * @return Scan request is sent if true is returned.
76  */
77 bool sl_btctrl_filter_scan_request_transmission_cb(sl_btctrl_packet_t packet);
78 
79 /** @} sl_btctrl_callbacks */
80 #endif
81