le_update_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_update Update API
14  *
15  * @ref le_update_interface.h "API Reference" <br>
16  * @ref legatoServicesUpdate <br>
17  * @ref legatoServicesUpdatePack <br>
18  * @ref conceptsUpdates <br>
19  * @ref getStartedUpdate
20  *
21  *
22  * This API uses @ref legatoServicesUpdatePack to update a target device software/firmware.
23  *
24  * Update packs can contain one or more @e tasks to be performed by the
25  * @ref basicRuntimeArch_updateDaemon.
26  *
27  * From the client view, the update service follows this state machine
28  * while doing an update:
29  *
30  *@image html updateApi.png
31  *
32  * @section API_Usage_Guideline API Usage Guidelines
33  *
34  * Typically, the API is used like this:
35  *
36  * 1. Client calls le_update_Start() providing a file descriptor for the update service to
37  * read the update pack and a notification callback function to call with updates.
38  *
39  * 2. Progress reports are sent to the client periodically through the notification function.
40  *
41  * 3. If the update fails, le_update_GetErrorCode() can be used to find out more info.
42  *
43  * 4. When the client is finished with the update, the client MUST call le_update_End() to
44  * relocate resources.
45  *
46  * To cancel an update before it finishes, call le_update_End().
47  *
48  * If the client disconnects before ending the update session, the session will automatically end.
49  * If the update is still in progress, it may be cancelled (if it's not too late).
50  *
51  *
52  * @section update_example Sample Code
53  *
54  * This C code sample calls an update service provider API to perform an update:
55  *
56  * @code
57  *
58  * void SoftwareUpdate(void)
59  * {
60  * int fd = 0; // Update data coming via STDIN
61  *
62  * le_result_t result = le_update_Start(fd, UpdateProgressHandler, NULL);
63  * if (result != LE_OK)
64  * {
65  * fprintf(stderr, "Update refused by server. Try again later.\n");
66  *
67  * // NOTE: It's okay to not delete the update here because we are exiting, so the handle
68  * // will be deleted automatically.
69  *
70  * exit(EXIT_FAILURE);
71  * }
72  * }
73  *
74  *
75  * // Sample callback function implementation.
76  * static void UpdateProgressHandler
77  * (
78  * le_update_State_t updateState, ///< Current state of the update.
79  * uint32 percentDone, ///< Percent done for current state.
80  * void* contextPtr ///< Context pointer (NULL).
81  * )
82  * {
83  * switch(updateState)
84  * {
85  * case LE_UPDATE_STATE_UNPACKING:
86  * fprintf(stdout, "Unpacking: %d%% \n", percentDone);
87  * break;
88  *
89  * case LE_UPDATE_STATE_DOWNLOAD_SUCCESS:
90  * le_update_Install();
91  * break;
92  *
93  * case LE_UPDATE_STATE_APPLYING:
94  * fprintf(stdout, "Applying: %d%% \n", percentDone);
95  * break;
96  *
97  * case LE_UPDATE_STATE_SUCCESS:
98  * fprintf(stdout, "\nSUCCESS\n");
99  * exit(EXIT_SUCCESS);
100  *
101  * case LE_UPDATE_STATE_FAILED:
102  * fprintf(stderr, "\nFAILED: error code %d\n", le_update_GetErrorCode());
103  * exit(EXIT_FAILURE);
104  * }
105  * }
106  *
107  * @endcode
108  *
109  * @section Update_API_System_Info Installed System Information
110  *
111  * It is possible to get the index and hash for all of the currently installed systems. The
112  * following is an example of how one would list all installed systems and their hashes.
113  *
114  * @code
115  *
116  * int32_t systemIndex = le_update_GetCurrentSysIndex();
117  *
118  * do
119  * {
120  * char hashBuffer[LE_LIMIT_MD5_STR_LEN + 1];
121  *
122  * if (le_update_GetSystemHash(systemIndex, hashBuffer, sizeof(hashBuffer)) == LE_OK)
123  * {
124  * LE_INFO("System: %d -- %s", systemIndex, hashBuffer);
125  * }
126  * else
127  * {
128  * LE_ERROR("System: %d -- NOT FOUND", systemIndex);
129  * }
130  * }
131  * while ((systemIndex = le_update_GetPreviousSystemIndex(systemIndex)) != -1);
132  *
133  * @endcode
134  *
135  * Copyright (C) Sierra Wireless Inc.
136  */
137 /**
138  * @file le_update_interface.h
139  *
140  * Legato @ref c_update include file.
141  *
142  * Copyright (C) Sierra Wireless Inc.
143  */
144 
145 #ifndef LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
146 #define LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
147 
148 
149 #include "legato.h"
150 
151 // Interface specific includes
152 #include "le_limit_interface.h"
153 
154 
155 //--------------------------------------------------------------------------------------------------
156 /**
157  * Type for handler called when a server disconnects.
158  */
159 //--------------------------------------------------------------------------------------------------
160 typedef void (*le_update_DisconnectHandler_t)(void *);
161 
162 //--------------------------------------------------------------------------------------------------
163 /**
164  *
165  * Connect the current client thread to the service providing this API. Block until the service is
166  * available.
167  *
168  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
169  * called before any other functions in this API. Normally, ConnectService is automatically called
170  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
171  *
172  * This function is created automatically.
173  */
174 //--------------------------------------------------------------------------------------------------
176 (
177  void
178 );
179 
180 //--------------------------------------------------------------------------------------------------
181 /**
182  *
183  * Try to connect the current client thread to the service providing this API. Return with an error
184  * if the service is not available.
185  *
186  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
187  * called before any other functions in this API. Normally, ConnectService is automatically called
188  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
189  *
190  * This function is created automatically.
191  *
192  * @return
193  * - LE_OK if the client connected successfully to the service.
194  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
195  * bound.
196  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
197  * - LE_COMM_ERROR if the Service Directory cannot be reached.
198  */
199 //--------------------------------------------------------------------------------------------------
201 (
202  void
203 );
204 
205 //--------------------------------------------------------------------------------------------------
206 /**
207  * Set handler called when server disconnection is detected.
208  *
209  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
210  * to continue without exiting, it should call longjmp() from inside the handler.
211  */
212 //--------------------------------------------------------------------------------------------------
214 (
215  le_update_DisconnectHandler_t disconnectHandler,
216  void *contextPtr
217 );
218 
219 //--------------------------------------------------------------------------------------------------
220 /**
221  *
222  * Disconnect the current client thread from the service providing this API.
223  *
224  * Normally, this function doesn't need to be called. After this function is called, there's no
225  * longer a connection to the service, and the functions in this API can't be used. For details, see
226  * @ref apiFilesC_client.
227  *
228  * This function is created automatically.
229  */
230 //--------------------------------------------------------------------------------------------------
232 (
233  void
234 );
235 
236 
237 //--------------------------------------------------------------------------------------------------
238 /**
239  * Different states in the update state machine. The state machine is maintained to track the
240  * update task underway.
241  *
242  * Example:
243  * for successful installation task, state transitions look like:
244  *
245  *@verbatim
246  --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
247  | |
248  +---------------------------------+-------> FAILED.
249 @endverbatim
250  */
251 //--------------------------------------------------------------------------------------------------
252 typedef enum
253 {
255  ///< Unpacking update data.
257  ///< Update data downloaded successfully.
259  ///< Applying update(i.e. installation/removal operation going on).
261  ///< Successfully completed all update task.
263  ///< Update failed due to some error or deletion request.
264 }
266 
267 
268 //--------------------------------------------------------------------------------------------------
269 /**
270  * Error code used to provide diagnostic information after a failed update.
271  *
272  * @note
273  * Additional information may also be available in the target device's system log.
274  */
275 //--------------------------------------------------------------------------------------------------
276 typedef enum
277 {
279  ///< No error.
281  ///< Encountered bad update package. Check logs.
283  ///< Something failed while doing update. Check logs.
285  ///< Error while doing security check of the package.
286 }
288 
289 
290 //--------------------------------------------------------------------------------------------------
291 /**
292  * Reference type used by Add/Remove functions for EVENT 'le_update_Progress'
293  */
294 //--------------------------------------------------------------------------------------------------
295 typedef struct le_update_ProgressHandler* le_update_ProgressHandlerRef_t;
296 
297 
298 //--------------------------------------------------------------------------------------------------
299 /**
300  * The client callback function (handler) passed to le_update_Start() must look like this.
301  */
302 //--------------------------------------------------------------------------------------------------
303 typedef void (*le_update_ProgressHandlerFunc_t)
304 (
305  le_update_State_t updateState,
306  ///< Current state of update.
307  uint32_t percentDone,
308  ///< Percent done for current state. For example, in state
309  ///< UNPACKING, a percentDone of 80 means that 80% of the update
310  ///< data has been unpacked.
311  void* contextPtr
312  ///<
313 );
314 
315 //--------------------------------------------------------------------------------------------------
316 /**
317  * Add handler function for EVENT 'le_update_Progress'
318  *
319  * Register for notification of the progress of a given update.
320  */
321 //--------------------------------------------------------------------------------------------------
323 (
325  ///< [IN] Progress handler
326  void* contextPtr
327  ///< [IN]
328 );
329 
330 //--------------------------------------------------------------------------------------------------
331 /**
332  * Remove handler function for EVENT 'le_update_Progress'
333  */
334 //--------------------------------------------------------------------------------------------------
336 (
338  ///< [IN]
339 );
340 
341 //--------------------------------------------------------------------------------------------------
342 /**
343  * Starts an update.
344  *
345  * Progress is reported via the progress handler callback.
346  *
347  * @return
348  * - LE_OK if accepted.
349  * - LE_BUSY if another update is in progress.
350  * - LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).
351  */
352 //--------------------------------------------------------------------------------------------------
354 (
355  int fd
356  ///< [IN] Open file descriptor from which the update can be read.
357 );
358 
359 //--------------------------------------------------------------------------------------------------
360 /**
361  * Install the update
362  *
363  * @return
364  * - LE_OK if installation started.
365  * - LE_BUSY if package download is not finished yet.
366  * - LE_FAULT if there is an error. Check logs
367  */
368 //--------------------------------------------------------------------------------------------------
370 (
371  void
372 );
373 
374 //--------------------------------------------------------------------------------------------------
375 /**
376  * Ends an update session. If the update isn't finished yet, cancels it.
377  */
378 //--------------------------------------------------------------------------------------------------
379 void le_update_End
380 (
381  void
382 );
383 
384 //--------------------------------------------------------------------------------------------------
385 /**
386  * Function to get error code when update fails.
387  *
388  * @return
389  * - Error code of encountered error.
390  * - ERR_NONE if update is in any other state.
391  */
392 //--------------------------------------------------------------------------------------------------
394 (
395  void
396 );
397 
398 //--------------------------------------------------------------------------------------------------
399 /**
400  * Get the index of the currently running system.
401  *
402  * @return The index of the running system.
403  */
404 //--------------------------------------------------------------------------------------------------
406 (
407  void
408 );
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Gets the hash ID for a given system.
413  *
414  * @return
415  * - LE_OK if no problems are encountered.
416  * - LE_NOT_FOUND if the given index does not correspond to an available system.
417  * - LE_OVERFLOW if the supplied buffer is too small.
418  * - LE_FORMAT_ERROR if there are problems reading the hash for the system.
419  */
420 //--------------------------------------------------------------------------------------------------
422 (
423  int32_t systemIndex,
424  ///< [IN] The system to read the hash for.
425  char* hashStr,
426  ///< [OUT] Buffer to hold the system hash string.
427  size_t hashStrSize
428  ///< [IN]
429 );
430 
431 //--------------------------------------------------------------------------------------------------
432 /**
433  * Get the index for the previous system in the chain, using the current system as a starting point.
434  *
435  * @return The index to the system that's previous to the given system. -1 is returned if the
436  * previous system was not found.
437  */
438 //--------------------------------------------------------------------------------------------------
440 (
441  int32_t systemIndex
442  ///< [IN] Get the system that's older than this system.
443 );
444 
445 #endif // LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
void le_update_End(void)
void(* le_update_DisconnectHandler_t)(void *)
Definition: le_update_interface.h:160
Update failed due to some error or deletion request.
Definition: le_update_interface.h:262
le_result_t
Definition: le_basics.h:35
le_update_ErrorCode_t
Definition: le_update_interface.h:276
Applying update(i.e. installation/removal operation going on).
Definition: le_update_interface.h:258
void le_update_RemoveProgressHandler(le_update_ProgressHandlerRef_t handlerRef)
void le_update_SetServerDisconnectHandler(le_update_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_update_Start(int fd)
struct le_update_ProgressHandler * le_update_ProgressHandlerRef_t
Definition: le_update_interface.h:295
Something failed while doing update. Check logs.
Definition: le_update_interface.h:282
Successfully completed all update task.
Definition: le_update_interface.h:260
void(* le_update_ProgressHandlerFunc_t)(le_update_State_t updateState, uint32_t percentDone, void *contextPtr)
Definition: le_update_interface.h:304
le_result_t le_update_TryConnectService(void)
le_update_ProgressHandlerRef_t le_update_AddProgressHandler(le_update_ProgressHandlerFunc_t handlerPtr, void *contextPtr)
le_update_State_t
Definition: le_update_interface.h:252
int32_t le_update_GetCurrentSysIndex(void)
le_result_t le_update_GetSystemHash(int32_t systemIndex, char *hashStr, size_t hashStrSize)
Update data downloaded successfully.
Definition: le_update_interface.h:256
Error while doing security check of the package.
Definition: le_update_interface.h:284
void le_update_ConnectService(void)
void le_update_DisconnectService(void)
le_result_t le_update_Install(void)
Unpacking update data.
Definition: le_update_interface.h:254
int32_t le_update_GetPreviousSystemIndex(int32_t systemIndex)
le_update_ErrorCode_t le_update_GetErrorCode(void)
No error.
Definition: le_update_interface.h:278
Encountered bad update package. Check logs.
Definition: le_update_interface.h:280