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 //--------------------------------------------------------------------------------------------------
161 /**
162  * Type for handler called when a server disconnects.
163  */
164 //--------------------------------------------------------------------------------------------------
165 typedef void (*le_update_DisconnectHandler_t)(void *);
166 
167 //--------------------------------------------------------------------------------------------------
168 /**
169  *
170  * Connect the current client thread to the service providing this API. Block until the service is
171  * available.
172  *
173  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
174  * called before any other functions in this API. Normally, ConnectService is automatically called
175  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
176  *
177  * This function is created automatically.
178  */
179 //--------------------------------------------------------------------------------------------------
181 (
182  void
183 );
184 
185 //--------------------------------------------------------------------------------------------------
186 /**
187  *
188  * Try to connect the current client thread to the service providing this API. Return with an error
189  * if the service is not available.
190  *
191  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
192  * called before any other functions in this API. Normally, ConnectService is automatically called
193  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
194  *
195  * This function is created automatically.
196  *
197  * @return
198  * - LE_OK if the client connected successfully to the service.
199  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
200  * bound.
201  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
202  * - LE_COMM_ERROR if the Service Directory cannot be reached.
203  */
204 //--------------------------------------------------------------------------------------------------
206 (
207  void
208 );
209 
210 //--------------------------------------------------------------------------------------------------
211 /**
212  * Set handler called when server disconnection is detected.
213  *
214  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
215  * to continue without exiting, it should call longjmp() from inside the handler.
216  */
217 //--------------------------------------------------------------------------------------------------
219 (
220  le_update_DisconnectHandler_t disconnectHandler,
221  void *contextPtr
222 );
223 
224 //--------------------------------------------------------------------------------------------------
225 /**
226  *
227  * Disconnect the current client thread from the service providing this API.
228  *
229  * Normally, this function doesn't need to be called. After this function is called, there's no
230  * longer a connection to the service, and the functions in this API can't be used. For details, see
231  * @ref apiFilesC_client.
232  *
233  * This function is created automatically.
234  */
235 //--------------------------------------------------------------------------------------------------
237 (
238  void
239 );
240 
241 
242 //--------------------------------------------------------------------------------------------------
243 /**
244  * Different states in the update state machine. The state machine is maintained to track the
245  * update task underway.
246  *
247  * Example:
248  * for successful installation task, state transitions look like:
249  *
250  *@verbatim
251  --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
252  | |
253  +---------------------------------+-------> FAILED.
254 @endverbatim
255  */
256 //--------------------------------------------------------------------------------------------------
257 
258 
259 //--------------------------------------------------------------------------------------------------
260 /**
261  * Error code used to provide diagnostic information after a failed update.
262  *
263  * @note
264  * Additional information may also be available in the target device's system log.
265  */
266 //--------------------------------------------------------------------------------------------------
267 
268 
269 //--------------------------------------------------------------------------------------------------
270 /**
271  * The client callback function (handler) passed to le_update_Start() must look like this.
272  */
273 //--------------------------------------------------------------------------------------------------
274 
275 
276 //--------------------------------------------------------------------------------------------------
277 /**
278  * Reference type used by Add/Remove functions for EVENT 'le_update_Progress'
279  */
280 //--------------------------------------------------------------------------------------------------
281 
282 
283 //--------------------------------------------------------------------------------------------------
284 /**
285  * Add handler function for EVENT 'le_update_Progress'
286  *
287  * Register for notification of the progress of a given update.
288  */
289 //--------------------------------------------------------------------------------------------------
290 le_update_ProgressHandlerRef_t le_update_AddProgressHandler
291 (
292  le_update_ProgressHandlerFunc_t handlerPtr,
293  ///< [IN] Progress handler
294  void* contextPtr
295  ///< [IN]
296 );
297 
298 //--------------------------------------------------------------------------------------------------
299 /**
300  * Remove handler function for EVENT 'le_update_Progress'
301  */
302 //--------------------------------------------------------------------------------------------------
304 (
305  le_update_ProgressHandlerRef_t handlerRef
306  ///< [IN]
307 );
308 
309 //--------------------------------------------------------------------------------------------------
310 /**
311  * Starts an update.
312  *
313  * Progress is reported via the progress handler callback.
314  *
315  * @return
316  * - LE_OK if accepted.
317  * - LE_BUSY if another update is in progress.
318  * - LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).
319  */
320 //--------------------------------------------------------------------------------------------------
322 (
323  int fd
324  ///< [IN] Open file descriptor from which the update can be read.
325 );
326 
327 //--------------------------------------------------------------------------------------------------
328 /**
329  * Install the update
330  *
331  * @return
332  * - LE_OK if installation started.
333  * - LE_BUSY if package download is not finished yet.
334  * - LE_FAULT if there is an error. Check logs
335  */
336 //--------------------------------------------------------------------------------------------------
338 (
339  void
340 );
341 
342 //--------------------------------------------------------------------------------------------------
343 /**
344  * Ends an update session. If the update isn't finished yet, cancels it.
345  */
346 //--------------------------------------------------------------------------------------------------
347 void le_update_End
348 (
349  void
350 );
351 
352 //--------------------------------------------------------------------------------------------------
353 /**
354  * Function to get error code when update fails.
355  *
356  * @return
357  * - Error code of encountered error.
358  * - ERR_NONE if update is in any other state.
359  */
360 //--------------------------------------------------------------------------------------------------
361 le_update_ErrorCode_t le_update_GetErrorCode
362 (
363  void
364 );
365 
366 //--------------------------------------------------------------------------------------------------
367 /**
368  * Get the index of the currently running system.
369  *
370  * @return The index of the running system.
371  */
372 //--------------------------------------------------------------------------------------------------
374 (
375  void
376 );
377 
378 //--------------------------------------------------------------------------------------------------
379 /**
380  * Gets the hash ID for a given system.
381  *
382  * @return
383  * - LE_OK if no problems are encountered.
384  * - LE_NOT_FOUND if the given index does not correspond to an available system.
385  * - LE_OVERFLOW if the supplied buffer is too small.
386  * - LE_FORMAT_ERROR if there are problems reading the hash for the system.
387  */
388 //--------------------------------------------------------------------------------------------------
390 (
391  int32_t systemIndex,
392  ///< [IN] The system to read the hash for.
393  char* hashStr,
394  ///< [OUT] Buffer to hold the system hash string.
395  size_t hashStrSize
396  ///< [IN]
397 );
398 
399 //--------------------------------------------------------------------------------------------------
400 /**
401  * Get the index for the previous system in the chain, using the current system as a starting point.
402  *
403  * @return The index to the system that's previous to the given system. -1 is returned if the
404  * previous system was not found.
405  */
406 //--------------------------------------------------------------------------------------------------
408 (
409  int32_t systemIndex
410  ///< [IN] Get the system that's older than this system.
411 );
412 
413 #endif // LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
void le_update_End(void)
void(* le_update_DisconnectHandler_t)(void *)
Definition: le_update_interface.h:165
le_result_t
Definition: le_basics.h:35
void le_update_RemoveProgressHandler(le_update_ProgressHandlerRef_t handlerRef)
le_result_t le_update_Start(int fd)
le_result_t le_update_TryConnectService(void)
le_update_ProgressHandlerRef_t le_update_AddProgressHandler(le_update_ProgressHandlerFunc_t handlerPtr, void *contextPtr)
int32_t le_update_GetCurrentSysIndex(void)
le_result_t le_update_GetSystemHash(int32_t systemIndex, char *hashStr, size_t hashStrSize)
void le_update_ConnectService(void)
void le_update_DisconnectService(void)
le_result_t le_update_Install(void)
#define LE_FULL_API
Definition: le_basics.h:288
int32_t le_update_GetPreviousSystemIndex(int32_t systemIndex)
le_update_ErrorCode_t le_update_GetErrorCode(void)
LE_FULL_API void le_update_SetServerDisconnectHandler(le_update_DisconnectHandler_t disconnectHandler, void *contextPtr)