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. */
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  */
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_ALERT_NONE
@ IAS_ALERT_NONE
Definition: ias.h:77
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. This contains all option and data needed for initialization of...
Definition: ias.h:116
IAS_ALERT_MILD
@ IAS_ALERT_MILD
Definition: ias.h:78
ias_evt_t::evt_type
ias_evt_type_t evt_type
Definition: ias.h:97
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
Definition: ias.h:117
IAS_EVT_ALERT_LEVEL_UPDATED
@ IAS_EVT_ALERT_LEVEL_UPDATED
Definition: ias.h:86
IAS_EVT_INVALID
@ IAS_EVT_INVALID
Definition: ias.h:85
ias_evt_t::alert_level
uint8_t alert_level
Definition: ias.h:98
IAS_ALERT_HIGH
@ IAS_ALERT_HIGH
Definition: ias.h:79
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.