le_update_common.h

Go to the documentation of this file.
1 
2 /*
3  * ====================== WARNING ======================
4  *
5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
6  * DO NOT MODIFY IN ANY WAY.
7  *
8  * ====================== WARNING ======================
9  */
10 /**
11  * @file le_update_common.h
12  *
13  * Type definitions for le_update.
14  *
15  */
16 #ifndef LE_UPDATE_COMMON_H_INCLUDE_GUARD
17 #define LE_UPDATE_COMMON_H_INCLUDE_GUARD
18 
19 
20 #include "legato.h"
21 
22 // Interface specific includes
23 #include "le_limit_common.h"
24 
25 #define IFGEN_LE_UPDATE_PROTOCOL_ID "17cd65c5c26efb8f22650432980df70f"
26 #define IFGEN_LE_UPDATE_MSG_SIZE 48
27 /** @addtogroup le_update
28  * @{ **/
29 
30 
31 //--------------------------------------------------------------------------------------------------
32 /**
33  * Different states in the update state machine. The state machine is maintained to track the
34  * update task underway.
35  *
36  * Example:
37  * for successful installation task, state transitions look like:
38  *
39  *@verbatim
40  --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
41  | |
42  +---------------------------------+-------> FAILED.
43 @endverbatim
44  */
45 //--------------------------------------------------------------------------------------------------
46 typedef enum
47 {
49  ///< Unpacking update data.
51  ///< Update data downloaded successfully.
53  ///< Applying update(i.e. installation/removal operation going on).
55  ///< Successfully completed all update task.
57  ///< Update failed due to some error or deletion request.
58 }
60 
61 
62 //--------------------------------------------------------------------------------------------------
63 /**
64  * Error code used to provide diagnostic information after a failed update.
65  *
66  * @note
67  * Additional information may also be available in the target device's system log.
68  */
69 //--------------------------------------------------------------------------------------------------
70 typedef enum
71 {
73  ///< No error.
75  ///< Encountered bad update package. Check logs.
77  ///< Something failed while doing update. Check logs.
79  ///< Error while doing security check of the package.
80 }
82 
83 
84 //--------------------------------------------------------------------------------------------------
85 /**
86  * Reference type used by Add/Remove functions for EVENT 'le_update_Progress'
87  */
88 //--------------------------------------------------------------------------------------------------
89 typedef struct le_update_ProgressHandler* le_update_ProgressHandlerRef_t;
90 
91 
92 //--------------------------------------------------------------------------------------------------
93 /**
94  * The client callback function (handler) passed to le_update_Start() must look like this.
95  */
96 //--------------------------------------------------------------------------------------------------
97 typedef void (*le_update_ProgressHandlerFunc_t)
98 (
99  le_update_State_t updateState,
100  ///< Current state of update.
101  uint32_t percentDone,
102  ///< Percent done for current state. For example, in state
103  ///< UNPACKING, a percentDone of 80 means that 80% of the update
104  ///< data has been unpacked.
105  void* contextPtr
106  ///<
107 );
108 
109 
110 //--------------------------------------------------------------------------------------------------
111 /**
112  * Get if this client bound locally.
113  */
114 //--------------------------------------------------------------------------------------------------
115 LE_SHARED bool ifgen_le_update_HasLocalBinding
116 (
117  void
118 );
119 
120 
121 //--------------------------------------------------------------------------------------------------
122 /**
123  * Init data that is common across all threads
124  */
125 //--------------------------------------------------------------------------------------------------
126 LE_SHARED void ifgen_le_update_InitCommonData
127 (
128  void
129 );
130 
131 
132 //--------------------------------------------------------------------------------------------------
133 /**
134  * Perform common initialization and open a session
135  */
136 //--------------------------------------------------------------------------------------------------
137 LE_SHARED le_result_t ifgen_le_update_OpenSession
138 (
139  le_msg_SessionRef_t _ifgen_sessionRef,
140  bool isBlocking
141 );
142 
143 //--------------------------------------------------------------------------------------------------
144 /**
145  * Add handler function for EVENT 'le_update_Progress'
146  *
147  * Register for notification of the progress of a given update.
148  */
149 //--------------------------------------------------------------------------------------------------
150 LE_SHARED le_update_ProgressHandlerRef_t ifgen_le_update_AddProgressHandler
151 (
152  le_msg_SessionRef_t _ifgen_sessionRef,
154  ///< [IN] Progress handler
155  void* contextPtr
156  ///< [IN]
157 );
158 
159 //--------------------------------------------------------------------------------------------------
160 /**
161  * Remove handler function for EVENT 'le_update_Progress'
162  */
163 //--------------------------------------------------------------------------------------------------
164 LE_SHARED void ifgen_le_update_RemoveProgressHandler
165 (
166  le_msg_SessionRef_t _ifgen_sessionRef,
168  ///< [IN]
169 );
170 
171 //--------------------------------------------------------------------------------------------------
172 /**
173  * Starts an update.
174  *
175  * Progress is reported via the progress handler callback.
176  *
177  * @return
178  * - LE_OK if accepted.
179  * - LE_BUSY if another update is in progress.
180  * - LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).
181  */
182 //--------------------------------------------------------------------------------------------------
183 LE_SHARED le_result_t ifgen_le_update_Start
184 (
185  le_msg_SessionRef_t _ifgen_sessionRef,
186  int fd
187  ///< [IN] Open file descriptor from which the update can be read.
188 );
189 
190 //--------------------------------------------------------------------------------------------------
191 /**
192  * Install the update
193  *
194  * @return
195  * - LE_OK if installation started.
196  * - LE_BUSY if package download is not finished yet.
197  * - LE_FAULT if there is an error. Check logs
198  */
199 //--------------------------------------------------------------------------------------------------
200 LE_SHARED le_result_t ifgen_le_update_Install
201 (
202  le_msg_SessionRef_t _ifgen_sessionRef
203 );
204 
205 //--------------------------------------------------------------------------------------------------
206 /**
207  * Ends an update session. If the update isn't finished yet, cancels it.
208  */
209 //--------------------------------------------------------------------------------------------------
210 LE_SHARED void ifgen_le_update_End
211 (
212  le_msg_SessionRef_t _ifgen_sessionRef
213 );
214 
215 //--------------------------------------------------------------------------------------------------
216 /**
217  * Function to get error code when update fails.
218  *
219  * @return
220  * - Error code of encountered error.
221  * - ERR_NONE if update is in any other state.
222  */
223 //--------------------------------------------------------------------------------------------------
224 LE_SHARED le_update_ErrorCode_t ifgen_le_update_GetErrorCode
225 (
226  le_msg_SessionRef_t _ifgen_sessionRef
227 );
228 
229 //--------------------------------------------------------------------------------------------------
230 /**
231  * Get the index of the currently running system.
232  *
233  * @return The index of the running system.
234  */
235 //--------------------------------------------------------------------------------------------------
236 LE_SHARED int32_t ifgen_le_update_GetCurrentSysIndex
237 (
238  le_msg_SessionRef_t _ifgen_sessionRef
239 );
240 
241 //--------------------------------------------------------------------------------------------------
242 /**
243  * Gets the hash ID for a given system.
244  *
245  * @return
246  * - LE_OK if no problems are encountered.
247  * - LE_NOT_FOUND if the given index does not correspond to an available system.
248  * - LE_OVERFLOW if the supplied buffer is too small.
249  * - LE_FORMAT_ERROR if there are problems reading the hash for the system.
250  */
251 //--------------------------------------------------------------------------------------------------
252 LE_SHARED le_result_t ifgen_le_update_GetSystemHash
253 (
254  le_msg_SessionRef_t _ifgen_sessionRef,
255  int32_t systemIndex,
256  ///< [IN] The system to read the hash for.
257  char* hashStr,
258  ///< [OUT] Buffer to hold the system hash string.
259  size_t hashStrSize
260  ///< [IN]
261 );
262 
263 //--------------------------------------------------------------------------------------------------
264 /**
265  * Get the index for the previous system in the chain, using the current system as a starting point.
266  *
267  * @return The index to the system that's previous to the given system. -1 is returned if the
268  * previous system was not found.
269  */
270 //--------------------------------------------------------------------------------------------------
271 LE_SHARED int32_t ifgen_le_update_GetPreviousSystemIndex
272 (
273  le_msg_SessionRef_t _ifgen_sessionRef,
274  int32_t systemIndex
275  ///< [IN] Get the system that's older than this system.
276 );
277 /** @} **/
278 #endif // LE_UPDATE_COMMON_H_INCLUDE_GUARD
le_update_ErrorCode_t
Definition: le_update_common.h:70
le_update_State_t
Definition: le_update_common.h:46
#define LE_SHARED
Definition: le_basics.h:287
le_result_t
Definition: le_basics.h:46
Encountered bad update package. Check logs.
Definition: le_update_common.h:74
Error while doing security check of the package.
Definition: le_update_common.h:78
Applying update(i.e. installation/removal operation going on).
Definition: le_update_common.h:52
Something failed while doing update. Check logs.
Definition: le_update_common.h:76
Successfully completed all update task.
Definition: le_update_common.h:54
Update data downloaded successfully.
Definition: le_update_common.h:50
Update failed due to some error or deletion request.
Definition: le_update_common.h:56
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860
No error.
Definition: le_update_common.h:72
Unpacking update data.
Definition: le_update_common.h:48
void(* le_update_ProgressHandlerFunc_t)(le_update_State_t updateState, uint32_t percentDone, void *contextPtr)
Definition: le_update_common.h:98
struct le_update_ProgressHandler * le_update_ProgressHandlerRef_t
Definition: le_update_common.h:89