1 /*
2 * Copyright (c) 2024 Vogl Electronic GmbH
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief hawkBit event header file
10 */
11
12 /**
13 * @brief hawkBit event API.
14 * @defgroup hawkbit_event hawkBit event API
15 * @ingroup hawkbit
16 * @{
17 */
18
19 #ifndef ZEPHYR_INCLUDE_MGMT_HAWKBIT_EVENT_H_
20 #define ZEPHYR_INCLUDE_MGMT_HAWKBIT_EVENT_H_
21
22 #include <zephyr/kernel.h>
23 #include <zephyr/sys/slist.h>
24
25 /**
26 * @brief hawkBit event type.
27 *
28 * @details These events are used to register the callback functions.
29 *
30 */
31 enum hawkbit_event_type {
32 /** Event triggered when there was an error */
33 HAWKBIT_EVENT_ERROR,
34 /** Event triggered when there was a networking error */
35 HAWKBIT_EVENT_ERROR_NETWORKING,
36 /** Event triggered when there was a permission error */
37 HAWKBIT_EVENT_ERROR_PERMISSION,
38 /** Event triggered when there was a metadata error */
39 HAWKBIT_EVENT_ERROR_METADATA,
40 /** Event triggered when there was a download error */
41 HAWKBIT_EVENT_ERROR_DOWNLOAD,
42 /** Event triggered when there was an allocation error */
43 HAWKBIT_EVENT_ERROR_ALLOC,
44 /** Event triggered when a new update was downloaded */
45 HAWKBIT_EVENT_UPDATE_DOWNLOADED,
46 /** Event triggered when there is no update available */
47 HAWKBIT_EVENT_NO_UPDATE,
48 /** Event triggered when the update was canceled by the server */
49 HAWKBIT_EVENT_CANCEL_UPDATE,
50 /** Event triggered before the download starts */
51 HAWKBIT_EVENT_START_DOWNLOAD,
52 /** Event triggered after the download ends */
53 HAWKBIT_EVENT_END_DOWNLOAD,
54 /** Event triggered before the hawkBit run starts */
55 HAWKBIT_EVENT_START_RUN,
56 /** Event triggered after the hawkBit run ends */
57 HAWKBIT_EVENT_END_RUN,
58 /** Event triggered before hawkBit does a reboot */
59 HAWKBIT_EVENT_BEFORE_REBOOT,
60 };
61
62 struct hawkbit_event_callback;
63
64 /**
65 * @typedef hawkbit_event_callback_handler_t
66 * @brief Define the application callback handler function signature
67 *
68 * @param cb Original struct hawkbit_event_callback owning this handler
69 * @param event The event that triggered the callback
70 *
71 * Note: cb pointer can be used to retrieve private data through
72 * CONTAINER_OF() if original struct hawkbit_event_callback is stored in
73 * another private structure.
74 */
75 typedef void (*hawkbit_event_callback_handler_t)(struct hawkbit_event_callback *cb,
76 enum hawkbit_event_type event);
77
78 /** @cond INTERNAL_HIDDEN */
79
80 /**
81 * @brief hawkBit callback structure
82 *
83 * Used to register a callback in the hawkBit callback list.
84 * As many callbacks as needed can be added as long as each of them
85 * are unique pointers of struct hawkbit_event_callback.
86 * Beware such structure should not be allocated on stack.
87 *
88 * Note: To help setting it, see hawkbit_event_init_callback() below
89 */
90 struct hawkbit_event_callback {
91 /** This is meant to be used internally and the user should not mess with it. */
92 sys_snode_t node;
93
94 /** Actual callback function being called when relevant. */
95 hawkbit_event_callback_handler_t handler;
96
97 /** The event type this callback is attached to. */
98 enum hawkbit_event_type event;
99 };
100
101 /** @endcond */
102
103
104 /**
105 * @brief Macro to create and initialize a struct hawkbit_event_callback properly.
106 *
107 * @details This macro can be used instead of hawkbit_event_init_callback().
108 *
109 * @param _callback Name of the callback structure
110 * @param _handler A valid handler function pointer.
111 * @param _event The event of ::hawkbit_event_type that will trigger the callback
112 */
113 #define HAWKBIT_EVENT_CREATE_CALLBACK(_callback, _handler, _event) \
114 struct hawkbit_event_callback _callback = { \
115 .handler = _handler, \
116 .event = _event, \
117 }
118
119 /**
120 * @brief Helper to initialize a struct hawkbit_event_callback properly
121 *
122 * @param callback A valid Application's callback structure pointer.
123 * @param handler A valid handler function pointer.
124 * @param event The event of ::hawkbit_event_type that will trigger the callback.
125 */
hawkbit_event_init_callback(struct hawkbit_event_callback * callback,hawkbit_event_callback_handler_t handler,enum hawkbit_event_type event)126 static inline void hawkbit_event_init_callback(struct hawkbit_event_callback *callback,
127 hawkbit_event_callback_handler_t handler,
128 enum hawkbit_event_type event)
129 {
130 __ASSERT(callback, "Callback pointer should not be NULL");
131 __ASSERT(handler, "Callback handler pointer should not be NULL");
132
133 callback->handler = handler;
134 callback->event = event;
135 }
136
137 /**
138 * @brief Add an application callback.
139 *
140 * @param cb A valid application's callback structure pointer.
141 *
142 * @return 0 if successful, negative errno code on failure.
143 */
144 int hawkbit_event_add_callback(struct hawkbit_event_callback *cb);
145
146 /**
147 * @brief Remove an application callback.
148 *
149 * @param cb A valid application's callback structure pointer.
150 *
151 * @return 0 if successful, negative errno code on failure.
152 */
153 int hawkbit_event_remove_callback(struct hawkbit_event_callback *cb);
154
155 /**
156 * @}
157 */
158
159 #endif /* ZEPHYR_INCLUDE_MGMT_HAWKBIT_EVENT_H_ */
160
