Line data Source code
1 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 1 : 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 : * Event triggered during initialisation when the current image is confirmed and the old
62 : * image is erased
63 : */
64 : HAWKBIT_EVENT_CONFIRMED_CURRENT_IMAGE,
65 : };
66 :
67 : struct hawkbit_event_callback;
68 :
69 : /**
70 : * @typedef hawkbit_event_callback_handler_t
71 : * @brief Define the application callback handler function signature
72 : *
73 : * @param cb Original struct hawkbit_event_callback owning this handler
74 : * @param event The event that triggered the callback
75 : *
76 : * Note: cb pointer can be used to retrieve private data through
77 : * CONTAINER_OF() if original struct hawkbit_event_callback is stored in
78 : * another private structure.
79 : */
80 1 : typedef void (*hawkbit_event_callback_handler_t)(struct hawkbit_event_callback *cb,
81 : enum hawkbit_event_type event);
82 :
83 : /** @cond INTERNAL_HIDDEN */
84 :
85 : /**
86 : * @brief hawkBit callback structure
87 : *
88 : * Used to register a callback in the hawkBit callback list.
89 : * As many callbacks as needed can be added as long as each of them
90 : * are unique pointers of struct hawkbit_event_callback.
91 : * Beware such structure should not be allocated on stack.
92 : *
93 : * Note: To help setting it, see hawkbit_event_init_callback() below
94 : */
95 : struct hawkbit_event_callback {
96 : /** This is meant to be used internally and the user should not mess with it. */
97 : sys_snode_t node;
98 :
99 : /** Actual callback function being called when relevant. */
100 : hawkbit_event_callback_handler_t handler;
101 :
102 : /** The event type this callback is attached to. */
103 : enum hawkbit_event_type event;
104 : };
105 :
106 : /** @endcond */
107 :
108 :
109 : /**
110 : * @brief Macro to create and initialize a struct hawkbit_event_callback properly.
111 : *
112 : * @details This macro can be used instead of hawkbit_event_init_callback().
113 : *
114 : * @param _callback Name of the callback structure
115 : * @param _handler A valid handler function pointer.
116 : * @param _event The event of ::hawkbit_event_type that will trigger the callback
117 : */
118 1 : #define HAWKBIT_EVENT_CREATE_CALLBACK(_callback, _handler, _event) \
119 : struct hawkbit_event_callback _callback = { \
120 : .handler = _handler, \
121 : .event = _event, \
122 : }
123 :
124 : /**
125 : * @brief Helper to initialize a struct hawkbit_event_callback properly
126 : *
127 : * @param callback A valid Application's callback structure pointer.
128 : * @param handler A valid handler function pointer.
129 : * @param event The event of ::hawkbit_event_type that will trigger the callback.
130 : */
131 1 : static inline void hawkbit_event_init_callback(struct hawkbit_event_callback *callback,
132 : hawkbit_event_callback_handler_t handler,
133 : enum hawkbit_event_type event)
134 : {
135 : __ASSERT(callback, "Callback pointer should not be NULL");
136 : __ASSERT(handler, "Callback handler pointer should not be NULL");
137 :
138 : callback->handler = handler;
139 : callback->event = event;
140 : }
141 :
142 : /**
143 : * @brief Add an application callback.
144 : *
145 : * @param cb A valid application's callback structure pointer.
146 : *
147 : * @return 0 if successful, negative errno code on failure.
148 : */
149 1 : int hawkbit_event_add_callback(struct hawkbit_event_callback *cb);
150 :
151 : /**
152 : * @brief Remove an application callback.
153 : *
154 : * @param cb A valid application's callback structure pointer.
155 : *
156 : * @return 0 if successful, negative errno code on failure.
157 : */
158 1 : int hawkbit_event_remove_callback(struct hawkbit_event_callback *cb);
159 :
160 : /**
161 : * @}
162 : */
163 :
164 : #endif /* ZEPHYR_INCLUDE_MGMT_HAWKBIT_EVENT_H_ */
|
