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. */
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. */
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  */
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. This contains all option and data needed for initialization of the s...
Definition: lls.h:115
LLS_ALERT_LEVEL_MILD_ALERT
@ LLS_ALERT_LEVEL_MILD_ALERT
Definition: lls.h:77
lls_alert_levels_t
lls_alert_levels_t
Definition: lls.h:75
lls_evt_t::evt_type
lls_evt_type_t evt_type
Definition: lls.h:96
LLS_ALERT_LEVEL_HIGH_ALERT
@ LLS_ALERT_LEVEL_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
Definition: lls.h:76
lls_init_t::initial_alert_level
lls_alert_levels_t initial_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:290
LLS_EVT_LINK_LOSS_ALERT
@ LLS_EVT_LINK_LOSS_ALERT
Definition: lls.h:85
LLS_EVT_INVALID
@ LLS_EVT_INVALID
Definition: lls.h:84
lls_init_t::evt_handler
lls_evt_handler_t evt_handler
Definition: lls.h:116
lls_evt_t::alert_level
lls_alert_levels_t alert_level
Definition: lls.h:97