lls_c.h
Go to the documentation of this file.
1 /**
2  *****************************************************************************************
3  *
4  * @file lls_c.h
5  *
6  * @brief Link Loss Service Client 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  */
42 
43 /**
44  * @defgroup BLE_SDK_LLS_C Link Loss Service Client (LLS_C)
45  * @{
46  * @brief Link Loss Service Client module.
47  *
48  * @details The Link Loss Service Client contains the APIs and types, which can be used by the
49  * application to discovery of Link Loss Service of peer and interact with it.
50  *
51  * The application must provide an event handler to register, then call \ref lls_client_init().
52  * After Link Loss Service Client discoveries peer Link Loss Service, application can call
53  * \ref lls_c_alert_level_set() and \ref lls_c_alert_level_read() to get Alert Level from peer.
54  */
55 
56 #ifndef __LLS_C_H__
57 #define __LLS_C_H__
58 
59 #include "gr_includes.h"
60 #include "ble_prf_types.h"
61 #include "custom_config.h"
62 #include <stdint.h>
63 #include <stdbool.h>
64 
65 /**
66  * @defgroup LLS_C_MACRO Defines
67  * @{
68  */
69 #define LLS_C_CONNECTION_MAX 10 /**< Maximum number of LLS Client connections. */
70 /** @} */
71 
72 /**
73  * @defgroup LLS_C_ENUM Enumerations
74  * @{
75  */
76 /**@brief Link Loss Service Client alert levels. */
77 typedef enum
78 {
79  LLS_C_ALERT_LEVEL_NO_ALERT, /**< No alert. */
80  LLS_C_ALERT_LEVEL_MILD_ALERT, /**< Mild alert. */
81  LLS_C_ALERT_LEVEL_HIGH_ALERT, /**< High alert. */
83 
84 /**@brief Link Loss Service Client event type. */
85 typedef enum
86 {
87  LLS_C_EVT_INVALID, /**< LLS Client invalid event. */
88  LLS_C_EVT_DISCOVERY_COMPLETE, /**< LLS Client has found LLS service and its characteristics. */
89  LLS_C_EVT_DISCOVERY_FAIL, /**< LLS Client found LLS service failed because of invalid operation or no found at the peer. */
90  LLS_C_EVT_ALERT_LEVEL_SET_SUCCESS, /**< LLS Client has set Alert Level characteristics. */
91  LLS_C_EVT_ALERT_LEVEL_SET_ERR, /**< Error occured when LLS Client set Alert Level characteristics. */
92  LLS_C_EVT_ALERT_LEVEL_RECEIVE, /**< LLS Client has received Alert Level value. */
94 /** @} */
95 
96 /**
97  * @defgroup LLS_C_STRUCT Structures
98  * @{
99  */
100 /**@brief Handles on the connected peer device needed to interact with it. */
101 typedef struct
102 {
103  uint16_t lls_srvc_start_handle; /**< LLS Service start handle. */
104  uint16_t lls_srvc_end_handle; /**< LLS Service end handle. */
105  uint16_t lls_alert_level_handle; /**< LLS Alert Level characteristic Value handle which has been got from peer. */
107 
108 /**@brief Link Loss Service Client event. */
109 typedef struct
110 {
111  uint8_t conn_idx; /**< The connection index. */
112  lls_c_evt_type_t evt_type; /**< LLS Client event type. */
113  lls_c_alert_level_t alert_level; /**< Alert level. */
114 } lls_c_evt_t;
115 /** @} */
116 
117 /**
118  * @defgroup LLS_C_TYPEDEF Typedefs
119  * @{
120  */
121 /**@brief Link Loss Service Client event handler type. */
122 typedef void (*lls_c_evt_handler_t)(lls_c_evt_t *p_evt);
123 /** @} */
124 
125 /**
126  * @defgroup LLS_C_FUNCTION Functions
127  * @{
128  */
129 /**
130  *****************************************************************************************
131  * @brief Register LLS Client event handler.
132  *
133  * @param[in] evt_handler: Link Loss Service Client event handler.
134  *
135  * @return Result of initialization.
136  *****************************************************************************************
137  */
139 
140 /**
141  *****************************************************************************************
142  * @brief Discovery Link Loss Service on peer.
143  *
144  * @param[in] conn_idx: Index of connection.
145  *
146  * @return Operation result.
147  *****************************************************************************************
148  */
150 
151 /**
152  *****************************************************************************************
153  * @brief Set peer Alert Level.
154  *
155  * @param[in] conn_idx: Index of connection.
156  * @param[in] alert_level: Alert level.
157  *
158  * @return Operation result.
159  *****************************************************************************************
160  */
161 sdk_err_t lls_c_alert_level_set(uint8_t conn_idx, lls_c_alert_level_t alert_level);
162 
163 /**
164  *****************************************************************************************
165  * @brief Read Alert Level characteristic value.
166  *
167  * @param[in] conn_idx: Index of connection.
168  *
169  * @return Operation result.
170  *****************************************************************************************
171  */
173 /** @} */
174 
175 #endif
176 /** @} */
177 /** @} */
lls_c_evt_type_t
lls_c_evt_type_t
Link Loss Service Client event type.
Definition: lls_c.h:86
LLS_C_EVT_ALERT_LEVEL_RECEIVE
@ LLS_C_EVT_ALERT_LEVEL_RECEIVE
Definition: lls_c.h:92
lls_c_evt_t::conn_idx
uint8_t conn_idx
Definition: lls_c.h:111
lls_client_init
sdk_err_t lls_client_init(lls_c_evt_handler_t evt_handler)
Register LLS Client event handler.
lls_c_evt_handler_t
void(* lls_c_evt_handler_t)(lls_c_evt_t *p_evt)
Link Loss Service Client event handler type.
Definition: lls_c.h:122
LLS_C_EVT_ALERT_LEVEL_SET_ERR
@ LLS_C_EVT_ALERT_LEVEL_SET_ERR
Definition: lls_c.h:91
gr_includes.h
Include Files API.
LLS_C_ALERT_LEVEL_MILD_ALERT
@ LLS_C_ALERT_LEVEL_MILD_ALERT
Definition: lls_c.h:80
lls_c_alert_level_read
sdk_err_t lls_c_alert_level_read(uint8_t conn_idx)
Read Alert Level characteristic value.
LLS_C_EVT_ALERT_LEVEL_SET_SUCCESS
@ LLS_C_EVT_ALERT_LEVEL_SET_SUCCESS
Definition: lls_c.h:90
LLS_C_EVT_INVALID
@ LLS_C_EVT_INVALID
Definition: lls_c.h:87
lls_c_disc_srvc_start
sdk_err_t lls_c_disc_srvc_start(uint8_t conn_idx)
Discovery Link Loss Service on peer.
lls_c_alert_level_t
lls_c_alert_level_t
Link Loss Service Client alert levels.
Definition: lls_c.h:78
lls_c_evt_t::alert_level
lls_c_alert_level_t alert_level
Definition: lls_c.h:113
lls_c_handles_t::lls_srvc_start_handle
uint16_t lls_srvc_start_handle
Definition: lls_c.h:103
ble_prf_types.h
Profile/Service Common Types.
LLS_C_EVT_DISCOVERY_FAIL
@ LLS_C_EVT_DISCOVERY_FAIL
Definition: lls_c.h:89
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
lls_c_evt_t::evt_type
lls_c_evt_type_t evt_type
Definition: lls_c.h:112
LLS_C_ALERT_LEVEL_NO_ALERT
@ LLS_C_ALERT_LEVEL_NO_ALERT
Definition: lls_c.h:79
LLS_C_ALERT_LEVEL_HIGH_ALERT
@ LLS_C_ALERT_LEVEL_HIGH_ALERT
Definition: lls_c.h:81
lls_c_handles_t::lls_alert_level_handle
uint16_t lls_alert_level_handle
Definition: lls_c.h:105
lls_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: lls_c.h:102
LLS_C_EVT_DISCOVERY_COMPLETE
@ LLS_C_EVT_DISCOVERY_COMPLETE
Definition: lls_c.h:88
lls_c_alert_level_set
sdk_err_t lls_c_alert_level_set(uint8_t conn_idx, lls_c_alert_level_t alert_level)
Set peer Alert Level.
lls_c_evt_t
Link Loss Service Client event.
Definition: lls_c.h:110
lls_c_handles_t::lls_srvc_end_handle
uint16_t lls_srvc_end_handle
Definition: lls_c.h:104