ias.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file ias.h
5 *
6 * @brief Immediate Alarm 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_IAS Immediate Alarm Service (IAS)
46 * @{
47 * @brief Definitions and prototypes for the IAS interface.
48 *
49 * @details The Immediate Alert Service exposes a control point to allow a peer device to cause
50 * the device to immediately alert.
51 *
52 * The application must provide an event handler to set \ref ias_init_t.evt_handler.
53 * After \ref ias_init_t variable is initialized, the application must call \ref ias_service_init()
54 * to add the Immediate Alert Service and Alert Level characteristic to the BLE Stack database,
55 * the service will notify the application when the value of Alert Level characteristic is changed
56 * by the peer device.
57 *
58 * This module also provides \ref ias_alert_level_get() function to the
59 * application to poll the current value of Alert Level characteristic.
60 *
61 */
62
63 #ifndef __IAS_H__
64 #define __IAS_H__
65
66 #include "gr_includes.h"
67 #include "custom_config.h"
68 #include <stdint.h>
69
70 /**
71 * @defgroup IAS_ENUM Enumerations
72 * @{
73 */
74 /**@brief Immediate Alert Service Alert levels. */
75 enum
76 {
77 IAS_ALERT_NONE, /**< No alert. */
78 IAS_ALERT_MILD, /**< Mild alert. */
79 IAS_ALERT_HIGH, /**< High alert. */
80 };
81
82 /**@brief Immediate Alert Service event type. */
83 typedef enum
84 {
85 IAS_EVT_INVALID, /**< Invalid IAS event. */
86 IAS_EVT_ALERT_LEVEL_UPDATED, /**< Alert Level Updated event. */
87 }ias_evt_type_t;
88 /** @} */
89
90 /**
91 * @defgroup IAS_STRUCT Structures
92 * @{
93 */
94 /**@brief Immediate Alert Service event. */
95 typedef struct
96 {
97 ias_evt_type_t evt_type; /**< Type of event. */
98 uint8_t alert_level; /**< New value of Alert level. */
99 }ias_evt_t;
100 /** @} */
101
102 /**
103 * @defgroup IAS_TYPEDEF Typedefs
104 * @{
105 */
106 /**@brief Immediate Alert Service event handler type. */
107 typedef void (*ias_evt_handler_t)(ias_evt_t *p_evt);
108 /** @} */
109
110 /**
111 * @addtogroup IAS_STRUCT Structures
112 * @{
113 */
114 /**@brief Immediate Alert Service init stucture. This contains all option and data needed for initialization of the service. */
115 typedef struct
116 {
117 ias_evt_handler_t evt_handler; /**< Immediate Alert Service event handler. */
118 } ias_init_t;
119 /** @} */
120
121 /**
122 * @defgroup IAS_FUNCTION Functions
123 * @{
124 */
125 /**
126 *****************************************************************************************
127 * @brief Initialize a Immediate Alert Service instance and add in the BLE Stack database.
128 *
129 * @param[in] p_ias_init: Pointer to Immediate Aler Service initialization variable.
130 *
131 * @return Result of service initialization.
132 *****************************************************************************************
133 */
134 sdk_err_t ias_service_init(ias_init_t *p_ias_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 ias_alert_level_get(uint8_t *p_alert_level);
146 /** @} */
147
148 #endif
149 /** @} */
150 /** @} */
ias_evt_t
Immediate Alert Service event.
Definition: ias.h:96
ias_evt_type_t
ias_evt_type_t
Immediate Alert Service event type.
Definition: ias.h:84
ias_evt_handler_t
void(* ias_evt_handler_t)(ias_evt_t *p_evt)
Immediate Alert Service event handler type.
Definition: ias.h:107
ias_alert_level_get
sdk_err_t ias_alert_level_get(uint8_t *p_alert_level)
Get current value of alert level characteristic.
gr_includes.h
Include Files API.
ias_init_t
Immediate Alert Service init stucture.
Definition: ias.h:116
ias_evt_t::evt_type
ias_evt_type_t evt_type
Type of event.
Definition: ias.h:97
IAS_ALERT_HIGH
@ IAS_ALERT_HIGH
High alert.
Definition: ias.h:79
IAS_ALERT_NONE
@ IAS_ALERT_NONE
No alert.
Definition: ias.h:77
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
ias_init_t::evt_handler
ias_evt_handler_t evt_handler
Immediate Alert Service event handler.
Definition: ias.h:117
IAS_ALERT_MILD
@ IAS_ALERT_MILD
Mild alert.
Definition: ias.h:78
IAS_EVT_ALERT_LEVEL_UPDATED
@ IAS_EVT_ALERT_LEVEL_UPDATED
Alert Level Updated event.
Definition: ias.h:86
IAS_EVT_INVALID
@ IAS_EVT_INVALID
Invalid IAS event.
Definition: ias.h:85
ias_evt_t::alert_level
uint8_t alert_level
New value of Alert level.
Definition: ias.h:98
ias_service_init
sdk_err_t ias_service_init(ias_init_t *p_ias_init)
Initialize a Immediate Alert Service instance and add in the BLE Stack database.