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  * // Register for progress notifications.
63  * le_update_AddProgressHandler(UpdateProgressHandler, NULL);
64  *
65  * // Start update process(asynchronous). Completion will be notified via callback function.
66  * le_result_t result = le_update_Start(fd);
67  * if (result != LE_OK)
68  * {
69  * fprintf(stderr, "Update refused by server. Try again later.\n");
70  *
71  * // NOTE: It's okay to not delete the update here because we are exiting, so the handle
72  * // will be deleted automatically.
73  *
74  * exit(EXIT_FAILURE);
75  * }
76  * }
77  *
78  *
79  * // Sample callback function implementation.
80  * static void UpdateProgressHandler
81  * (
82  * le_update_State_t updateState, ///< Current state of the update.
83  * uint32 percentDone, ///< Percent done for current state.
84  * void* contextPtr ///< Context pointer (NULL).
85  * )
86  * {
87  * switch(updateState)
88  * {
89  * case LE_UPDATE_STATE_UNPACKING:
90  * fprintf(stdout, "Unpacking: %d%% \n", percentDone);
91  * break;
92  *
93  * case LE_UPDATE_STATE_DOWNLOAD_SUCCESS:
94  * le_update_Install();
95  * break;
96  *
97  * case LE_UPDATE_STATE_APPLYING:
98  * fprintf(stdout, "Applying: %d%% \n", percentDone);
99  * break;
100  *
101  * case LE_UPDATE_STATE_SUCCESS:
102  * fprintf(stdout, "\nSUCCESS\n");
103  * exit(EXIT_SUCCESS);
104  *
105  * case LE_UPDATE_STATE_FAILED:
106  * fprintf(stderr, "\nFAILED: error code %d\n", le_update_GetErrorCode());
107  * exit(EXIT_FAILURE);
108  * }
109  * }
110  *
111  * @endcode
112  *
113  * @section Update_API_System_Info Installed System Information
114  *
115  * It is possible to get the index and hash for all of the currently installed systems. The
116  * following is an example of how one would list all installed systems and their hashes.
117  *
118  * @code
119  *
120  * int32_t systemIndex = le_update_GetCurrentSysIndex();
121  *
122  * do
123  * {
124  * char hashBuffer[LE_LIMIT_MD5_STR_LEN + 1];
125  *
126  * if (le_update_GetSystemHash(systemIndex, hashBuffer, sizeof(hashBuffer)) == LE_OK)
127  * {
128  * LE_INFO("System: %d -- %s", systemIndex, hashBuffer);
129  * }
130  * else
131  * {
132  * LE_ERROR("System: %d -- NOT FOUND", systemIndex);
133  * }
134  * }
135  * while ((systemIndex = le_update_GetPreviousSystemIndex(systemIndex)) != -1);
136  *
137  * @endcode
138  *
139  * Copyright (C) Sierra Wireless Inc.
140  */
141 /**
142  * @file le_update_interface.h
143  *
144  * Legato @ref c_update include file.
145  *
146  * Copyright (C) Sierra Wireless Inc.
147  */
148 
149 #ifndef LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
150 #define LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
151 
152 
153 #include "legato.h"
154 
155 // Interface specific includes
156 #include "le_limit_interface.h"
157 
158 // Internal includes for this interface
159 #include "le_update_common.h"
160 /** @addtogroup le_update le_update API Reference
161  * @{
162  * @file le_update_common.h
163  * @file le_update_interface.h **/
164 //--------------------------------------------------------------------------------------------------
165 /**
166  * Type for handler called when a server disconnects.
167  */
168 //--------------------------------------------------------------------------------------------------
169 typedef void (*le_update_DisconnectHandler_t)(void *);
170 
171 //--------------------------------------------------------------------------------------------------
172 /**
173  *
174  * Connect the current client thread to the service providing this API. Block until the service is
175  * available.
176  *
177  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
178  * called before any other functions in this API. Normally, ConnectService is automatically called
179  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
180  *
181  * This function is created automatically.
182  */
183 //--------------------------------------------------------------------------------------------------
185 (
186  void
187 );
188 
189 //--------------------------------------------------------------------------------------------------
190 /**
191  *
192  * Try to connect the current client thread to the service providing this API. Return with an error
193  * if the service is not available.
194  *
195  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
196  * called before any other functions in this API. Normally, ConnectService is automatically called
197  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
198  *
199  * This function is created automatically.
200  *
201  * @return
202  * - LE_OK if the client connected successfully to the service.
203  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
204  * bound.
205  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
206  * - LE_COMM_ERROR if the Service Directory cannot be reached.
207  */
208 //--------------------------------------------------------------------------------------------------
210 (
211  void
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Set handler called when server disconnection is detected.
217  *
218  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
219  * to continue without exiting, it should call longjmp() from inside the handler.
220  */
221 //--------------------------------------------------------------------------------------------------
223 (
224  le_update_DisconnectHandler_t disconnectHandler,
225  void *contextPtr
226 );
227 
228 //--------------------------------------------------------------------------------------------------
229 /**
230  *
231  * Disconnect the current client thread from the service providing this API.
232  *
233  * Normally, this function doesn't need to be called. After this function is called, there's no
234  * longer a connection to the service, and the functions in this API can't be used. For details, see
235  * @ref apiFilesC_client.
236  *
237  * This function is created automatically.
238  */
239 //--------------------------------------------------------------------------------------------------
241 (
242  void
243 );
244 
245 
246 //--------------------------------------------------------------------------------------------------
247 /**
248  * Different states in the update state machine. The state machine is maintained to track the
249  * update task underway.
250  *
251  * Example:
252  * for successful installation task, state transitions look like:
253  *
254  *@verbatim
255  --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
256  | |
257  +---------------------------------+-------> FAILED.
258 @endverbatim
259  */
260 //--------------------------------------------------------------------------------------------------
261 
262 
263 //--------------------------------------------------------------------------------------------------
264 /**
265  * Error code used to provide diagnostic information after a failed update.
266  *
267  * @note
268  * Additional information may also be available in the target device's system log.
269  */
270 //--------------------------------------------------------------------------------------------------
271 
272 
273 //--------------------------------------------------------------------------------------------------
274 /**
275  * The client callback function (handler) passed to le_update_Start() must look like this.
276  */
277 //--------------------------------------------------------------------------------------------------
278 
279 
280 //--------------------------------------------------------------------------------------------------
281 /**
282  * Reference type used by Add/Remove functions for EVENT 'le_update_Progress'
283  */
284 //--------------------------------------------------------------------------------------------------
285 
286 
287 //--------------------------------------------------------------------------------------------------
288 /**
289  * Add handler function for EVENT 'le_update_Progress'
290  *
291  * Register for notification of the progress of a given update.
292  */
293 //--------------------------------------------------------------------------------------------------
295 (
297  ///< [IN] Progress handler
298  void* contextPtr
299  ///< [IN]
300 );
301 
302 //--------------------------------------------------------------------------------------------------
303 /**
304  * Remove handler function for EVENT 'le_update_Progress'
305  */
306 //--------------------------------------------------------------------------------------------------
308 (
310  ///< [IN]
311 );
312 
313 //--------------------------------------------------------------------------------------------------
314 /**
315  * Starts an update.
316  *
317  * Progress is reported via the progress handler callback.
318  *
319  * @return
320  * - LE_OK if accepted.
321  * - LE_BUSY if another update is in progress.
322  * - LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).
323  */
324 //--------------------------------------------------------------------------------------------------
326 (
327  int fd
328  ///< [IN] Open file descriptor from which the update can be read.
329 );
330 
331 //--------------------------------------------------------------------------------------------------
332 /**
333  * Install the update
334  *
335  * @return
336  * - LE_OK if installation started.
337  * - LE_BUSY if package download is not finished yet.
338  * - LE_FAULT if there is an error. Check logs
339  */
340 //--------------------------------------------------------------------------------------------------
342 (
343  void
344 );
345 
346 //--------------------------------------------------------------------------------------------------
347 /**
348  * Ends an update session. If the update isn't finished yet, cancels it.
349  */
350 //--------------------------------------------------------------------------------------------------
351 void le_update_End
352 (
353  void
354 );
355 
356 //--------------------------------------------------------------------------------------------------
357 /**
358  * Function to get error code when update fails.
359  *
360  * @return
361  * - Error code of encountered error.
362  * - ERR_NONE if update is in any other state.
363  */
364 //--------------------------------------------------------------------------------------------------
366 (
367  void
368 );
369 
370 //--------------------------------------------------------------------------------------------------
371 /**
372  * Get the index of the currently running system.
373  *
374  * @return The index of the running system.
375  */
376 //--------------------------------------------------------------------------------------------------
378 (
379  void
380 );
381 
382 //--------------------------------------------------------------------------------------------------
383 /**
384  * Gets the hash ID for a given system.
385  *
386  * @return
387  * - LE_OK if no problems are encountered.
388  * - LE_NOT_FOUND if the given index does not correspond to an available system.
389  * - LE_OVERFLOW if the supplied buffer is too small.
390  * - LE_FORMAT_ERROR if there are problems reading the hash for the system.
391  */
392 //--------------------------------------------------------------------------------------------------
394 (
395  int32_t systemIndex,
396  ///< [IN] The system to read the hash for.
397  char* hashStr,
398  ///< [OUT] Buffer to hold the system hash string.
399  size_t hashStrSize
400  ///< [IN]
401 );
402 
403 //--------------------------------------------------------------------------------------------------
404 /**
405  * Get the index for the previous system in the chain, using the current system as a starting point.
406  *
407  * @return The index to the system that's previous to the given system. -1 is returned if the
408  * previous system was not found.
409  */
410 //--------------------------------------------------------------------------------------------------
412 (
413  int32_t systemIndex
414  ///< [IN] Get the system that's older than this system.
415 );
416 
417 /** @} **/
418 
419 #endif // LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
le_update_ErrorCode_t
Definition: le_update_common.h:70
LE_FULL_API void le_update_SetServerDisconnectHandler(le_update_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t
Definition: le_basics.h:46
int32_t le_update_GetCurrentSysIndex(void)
le_result_t le_update_Start(int fd)
int32_t le_update_GetPreviousSystemIndex(int32_t systemIndex)
le_update_ProgressHandlerRef_t le_update_AddProgressHandler(le_update_ProgressHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_update_Install(void)
le_update_ErrorCode_t le_update_GetErrorCode(void)
void le_update_End(void)
void(* le_update_DisconnectHandler_t)(void *)
Definition: le_update_interface.h:169
void le_update_RemoveProgressHandler(le_update_ProgressHandlerRef_t handlerRef)
le_result_t le_update_GetSystemHash(int32_t systemIndex, char *hashStr, size_t hashStrSize)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_update_TryConnectService(void)
void le_update_ConnectService(void)
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
void le_update_DisconnectService(void)