lls.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file lls.h
5 *
6 * @brief Link Loss Service API
7 *
8 *****************************************************************************************
9 * @attention
10 #####Copyright (c) 2019 GOODIX
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15 * Redistributions of source code must retain the above copyright
16 notice, this list of conditions and the following disclaimer.
17 * Redistributions in binary form must reproduce the above copyright
18 notice, this list of conditions and the following disclaimer in the
19 documentation and/or other materials provided with the distribution.
20 * Neither the name of GOODIX nor the names of its contributors may be used
21 to endorse or promote products derived from this software without
22 specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35 *****************************************************************************************
36 */
37
38 /**
39 * @addtogroup BLE_SRV BLE Services
40 * @{
41 * @brief Definitions and prototypes for the BLE Service interface.
42 */
43
44 /**
45 * @defgroup BLE_SDK_LLS Link Loss Service (LLS)
46 * @{
47 * @brief Definitions and prototypes for the LLS interface.
48 *
49 * @details The Link Loss Service uses the Alert Level characteristic to cause an alert in the
50 * device when the link is lost.
51 *
52 * The application must provide an event handler to set \ref lls_init_t.evt_handler.
53 * After \ref lls_init_t variable is initialized, the application must call \ref lls_service_init()
54 * to add Alert Level Characteristic to the BLE Stack database, the service will notify the application
55 * with the event handler when the link has been lost, and which Alert Level has been set.
56 *
57 * This module also provides \ref lls_alert_level_get() function to the
58 * application to poll the current value of Alert Level characteristic.
59 *
60 */
61
62 #ifndef __LLS_H__
63 #define __LLS_H__
64
65 #include "gr_includes.h"
66 #include "custom_config.h"
67 #include <stdint.h>
68
69 /**
70 * @defgroup LLS_ENUM Enumerations
71 * @{
72 */
73 /** Link Loss Service alert levels. */
74 typedef enum
75 {
76 LLS_ALERT_LEVEL_NO_ALERT, /**< No alert. */
77 LLS_ALERT_LEVEL_MILD_ALERT, /**< Mild alert. */
78 LLS_ALERT_LEVEL_HIGH_ALERT, /**< High alert. */
79 } lls_alert_levels_t;
80
81 /**@brief Link Loss Service event type. */
82 typedef enum
83 {
84 LLS_EVT_INVALID, /**< Invalid LLS event. */
85 LLS_EVT_LINK_LOSS_ALERT /**< Link loss alert event. */
86 } lls_evt_type_t;
87 /** @} */
88
89 /**
90 * @defgroup LLS_STRUCT Structures
91 * @{
92 */
93 /**@brief Link Loss Service event. */
94 typedef struct
95 {
96 lls_evt_type_t evt_type; /**< Type of event. */
97 lls_alert_levels_t alert_level; /**< Alert level. */
98 } lls_evt_t;
99 /** @} */
100
101 /**
102 * @defgroup LLS_TYPEDEF Typedefs
103 * @{
104 */
105 /**@brief Link Loss Service event handler type. */
106 typedef void (*lls_evt_handler_t)(lls_evt_t *p_evt);
107 /** @} */
108
109 /**
110 * @addtogroup LLS_STRUCT Structures
111 * @{
112 */
113 /**@brief Link Loss Service init stucture. This contains all option and data needed for initialization of the service. */
114 typedef struct
115 {
116 lls_evt_handler_t evt_handler; /**< Link Loss Service event handler. */
117 lls_alert_levels_t initial_alert_level; /**< Initial value of the alert level. */
118 } lls_init_t;
119 /** @} */
120
121 /**
122 * @defgroup LLS_FUNCTION Functions
123 * @{
124 */
125 /**
126 *****************************************************************************************
127 * @brief Initialize a Link Loss Service instance and add in ATT DB
128 *
129 * @param[in] p_lls_init: Pointer to Link Loss Service Service initialization variable
130 *
131 * @return Result of service initialization.
132 *****************************************************************************************
133 */
134 sdk_err_t lls_service_init(lls_init_t *p_lls_init);
135
136 /**
137 *****************************************************************************************
138 * @brief Get current value of alert level characteristic.
139 *
140 * @param[out] p_alert_level: Pointer to the current value of alert level
141 *
142 * @return BLE_SDK_SUCCESS on success, otherwise an error code
143 *****************************************************************************************
144 */
145 sdk_err_t lls_alert_level_get(uint8_t *p_alert_level);
146 /** @} */
147
148 #endif
149 /** @} */
150 /** @} */
lls_evt_type_t
lls_evt_type_t
Link Loss Service event type.
Definition: lls.h:83
lls_init_t
Link Loss Service init stucture.
Definition: lls.h:115
LLS_ALERT_LEVEL_MILD_ALERT
@ LLS_ALERT_LEVEL_MILD_ALERT
Mild alert.
Definition: lls.h:77
lls_alert_levels_t
lls_alert_levels_t
Link Loss Service alert levels.
Definition: lls.h:75
lls_evt_t::evt_type
lls_evt_type_t evt_type
Type of event.
Definition: lls.h:96
LLS_ALERT_LEVEL_HIGH_ALERT
@ LLS_ALERT_LEVEL_HIGH_ALERT
High alert.
Definition: lls.h:78
lls_service_init
sdk_err_t lls_service_init(lls_init_t *p_lls_init)
Initialize a Link Loss Service instance and add in ATT DB.
gr_includes.h
Include Files API.
LLS_ALERT_LEVEL_NO_ALERT
@ LLS_ALERT_LEVEL_NO_ALERT
No alert.
Definition: lls.h:76
lls_init_t::initial_alert_level
lls_alert_levels_t initial_alert_level
Initial value of the alert level.
Definition: lls.h:117
lls_evt_t
Link Loss Service event.
Definition: lls.h:95
lls_alert_level_get
sdk_err_t lls_alert_level_get(uint8_t *p_alert_level)
Get current value of alert level characteristic.
lls_evt_handler_t
void(* lls_evt_handler_t)(lls_evt_t *p_evt)
Link Loss Service event handler type.
Definition: lls.h:106
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
LLS_EVT_LINK_LOSS_ALERT
@ LLS_EVT_LINK_LOSS_ALERT
Link loss alert event.
Definition: lls.h:85
LLS_EVT_INVALID
@ LLS_EVT_INVALID
Invalid LLS event.
Definition: lls.h:84
lls_init_t::evt_handler
lls_evt_handler_t evt_handler
Link Loss Service event handler.
Definition: lls.h:116
lls_evt_t::alert_level
lls_alert_levels_t alert_level
Alert level.
Definition: lls.h:97