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. */
82 } lls_c_alert_level_t;
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. */
93 } lls_c_evt_type_t;
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. */
106 } lls_c_handles_t;
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 */
138 sdk_err_t lls_client_init(lls_c_evt_handler_t evt_handler);
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 */
149 sdk_err_t lls_c_disc_srvc_start(uint8_t conn_idx);
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 */
172 sdk_err_t lls_c_alert_level_read(uint8_t conn_idx);
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
LLS Client has received Alert Level value.
Definition: lls_c.h:92
lls_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
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
Error occured when LLS Client set Alert Level characteristics.
Definition: lls_c.h:91
gr_includes.h
Include Files API.
LLS_C_ALERT_LEVEL_MILD_ALERT
@ LLS_C_ALERT_LEVEL_MILD_ALERT
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
LLS Client has set Alert Level characteristics.
Definition: lls_c.h:90
LLS_C_EVT_INVALID
@ LLS_C_EVT_INVALID
LLS Client invalid event.
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
Alert level.
Definition: lls_c.h:113
lls_c_handles_t::lls_srvc_start_handle
uint16_t lls_srvc_start_handle
LLS Service 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
LLS Client found LLS service failed because of invalid operation or no found at the peer.
Definition: lls_c.h:89
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
lls_c_evt_t::evt_type
lls_c_evt_type_t evt_type
LLS Client event type.
Definition: lls_c.h:112
LLS_C_ALERT_LEVEL_NO_ALERT
@ LLS_C_ALERT_LEVEL_NO_ALERT
No alert.
Definition: lls_c.h:79
LLS_C_ALERT_LEVEL_HIGH_ALERT
@ LLS_C_ALERT_LEVEL_HIGH_ALERT
High alert.
Definition: lls_c.h:81
lls_c_handles_t::lls_alert_level_handle
uint16_t lls_alert_level_handle
LLS Alert Level characteristic Value handle which has been got from peer.
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
LLS Client has found LLS service and its characteristics.
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
LLS Service end handle.
Definition: lls_c.h:104