le_avc_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_le_avc AirVantage Connector API
14  *
15  * @ref le_avc_interface.h "API Reference" <br>
16  * @ref legatoServicesAirVantage "AirVantage Connector Platform Service"
17  *
18  *
19  * The AirVantage connector service provides an API to communicate with the AirVantage Server to
20  * download and install updates.
21  *
22  * @section c_le_avc_update Firmware/Application Updates
23  *
24  * The API for firmware/application update is divided into two parts:
25  * - Allow an App to contact the server for pending updates. If available,
26  * can select to download or install the update.
27  * - Allow an App to block an update from being installed. An App may need this if it's
28  * performing a critical operation that can't be interrupted (e.g., eCall). This is necessary
29  * as installing an update will cause the App to restart (either the App itself needs to restart
30  * or a firmware change causes the modem to reset).
31  *
32  * @subsection c_le_avc_user_agreement User Agreement
33  *
34  * By default, user agreements are disabled. This means that avcService automatically accepts
35  * requests from the server without asking for user approval: it initiates a connection to the
36  * server, download/install packages and reboots the target if needed. Thus, if no control app for
37  * the AirVantage service is present on the target, the daemon is still able to update the target.
38  *
39  * User agreements are persistent to reboot/update, they are stored in the file system. The default
40  * settings are only applied when the target boots the first time or when the configuration file is
41  * missing or corrupted. In all other cases, default configuration never overwrites the current one.
42  *
43  * When writing a control app for the AirVantage Service, it is up to the developer to ensure that
44  * user agreements have been enabled for all actions the control app performs. Otherwise, avcService
45  * will automatically accept server requests. User agreements can be retrieved and updated using
46  * le_avc_GetUserAgreement() and le_avc_SetUserAgreement().
47  *
48  * If user agreements are enabled and avcService can't communicate with the control app to report
49  * the pending requests, it waits for 3 minutes and tries again.
50  *
51  * There are 5 events that require user agreements:
52  * - LE_AVC_CONNECTION_PENDING
53  * - LE_AVC_DOWNLOAD_PENDING
54  * - LE_AVC_INSTALL_PENDING
55  * - LE_AVC_REBOOT_PENDING
56  * - LE_AVC_UNINSTALL_PENDING
57  *
58  * An app can respond to these user agreement notifications by opening a connection if the
59  * notification is connection pending or by accepting or deferring the operation if the notification
60  * is one of download, install, uninstall or reboot pending.
61  * If the user agreement is not accepted or deferred, a new notification is returned 30 minutes
62  * later.
63  *
64  * Whether avcService should forward these notifications to an app or act on these notifications by
65  * itself is determined by the individual configuration flags that enables or disables user
66  * agreement for these operations. If the user agreement flag is turned off for an operation,
67  * the default action by avcService is to automatically accept that pending operation. An app can
68  * register its handler by calling le_avc_AddStatusEventHandler() described in
69  * c_le_avc_update_control and the configuration flags can be set by le_avc_SetUserAgreement().
70  *
71  * Example of enabling user agreement for LE_AVC_DOWNLOAD_PENDING:
72  * @code
73  * le_result_t result;
74  * result = le_avc_SetUserAgreement(LE_AVC_USER_AGREEMENT_DOWNLOAD, true);
75  *
76  * if (result != LE_OK)
77  * {
78  * LE_ERROR("Failed to enable user agreement for download operation");
79  * }
80  * @endcode
81  *
82  * @subsection c_le_avc_update_control Update Control
83  *
84  * Any App can start a session with an AirVantage server to determine if there
85  * is a pending update. This is done with le_avc_StartSession().
86  *
87  * The current session can be stopped using le_avc_StopSession(). This suspends a download in
88  * progress if the user agreement for download is activated and change its state to download
89  * pending. Otherwise if the user agreement for download is not activated, a new connection is
90  * immediatly initiated by AVC in order to resume the download. However, it <b>won't stop</b>
91  * an install in progress.
92  * The status of a pending update is sent to all Apps registered for receiving a notification.
93  * An App can use le_avc_AddStatusEventHandler() to register a handler function to
94  * receive this notification. The notification will be received after a session is started.
95  *
96  * Example of registering an AVC handler and starting a session with fault checking:
97  * @code
98  * // Start AVC Session
99  * LE_INFO("AirVantage Connection Controller started.");
100  * le_avc_AddStatusEventHandler(avcStatusHandler, NULL); //register a AVC handler
101  *
102  * // Start AVC session. Note: AVC handler must be registered prior starting a session
103  * le_result_t result = le_avc_StartSession();
104  * if (LE_FAULT == result)
105  * {
106  * le_avc_StopSession();
107  * le_avc_StartSession();
108  * }
109  * @endcode
110  *
111  * An App can use le_avc_AddCommInfoHandler() to register a handler function and receive
112  * communication information notifications. This function returns a reference. To unregister
113  * the handler, le_avc_RemoveCommInfoHandler() should be called with the previously returned
114  * reference.
115  *
116  *
117  * Sometimes, @c avcService may decide to start a session with the AirVantage
118  * server; for instance if a call to le_avc_AcceptDownload() when the session is stopped,
119  * @c avcService will open a session to proceed with the download. In this case, a session started
120  * notification could also be received, even if le_avc_StartSession() is not called explicitly.
121  *
122  * @subsubsection c_le_avc_updateControl_pending Pending Updates
123  *
124  * There can only be one pending update at a time. To query the type of update, use
125  * le_avc_GetUpdateType(). App updates can call le_avc_GetAppUpdateName() to retrieve the App name.
126  *
127  * If a download is pending, le_avc_AcceptDownload() can be used to allow the update to be
128  * downloaded. An AirVantage session will be initiated if this api is called while there is no
129  * active AirVantage session. le_avc_DeferDownload() can be used to defer the download for the
130  * specified number of minutes. After the defer time has elapsed, the pending download notification
131  * will be re-sent again to all registered apps. le_avc_AcceptDownload() can be used to accept the
132  * download even before the defer timer expires. This behaviour is true for deferring install
133  * and uninstall as well.
134  *
135  * Once an update has been downloaded, a new notification will be received to indicate that an
136  * install is pending. Apps can then use le_avc_AcceptInstall() to allow the install to proceed.
137  *
138  * If an uninstall is pending, then le_avc_AcceptUninstall() can be used to allow the uninstall to
139  * proceed. To defer the decision, le_avc_DeferUninstall() can be used to defer the uninstall for
140  * the specified number of minutes. In case of an upgrade, the existing application will not be
141  * uninstalled after le_avc_AcceptUninstall() is called. le_avc_AcceptUninstall() is only used to
142  * signal the server to start downloading the new application. To proceed with an upgrade process,
143  * accept the uninstall of the existing version followed by accepting the download and install of
144  * the new version.
145  *
146  * @code
147  * switch (updateStatus)
148  * {
149  * case LE_AVC_DOWNLOAD_PENDING:
150  * LE_INFO("Accepting %s update.", GetUpdateType());
151  * res = le_avc_AcceptDownload();
152  * if (res != LE_OK)
153  * {
154  * LE_ERROR("Failed to accept download from AirVantage (%s)", LE_RESULT_TXT(res));
155  * }
156  * break;
157  *
158  * case LE_AVC_INSTALL_PENDING:
159  * LE_INFO("Accepting %s installation.", GetUpdateType());
160  * res = le_avc_AcceptInstall();
161  * if (res != LE_OK)
162  * {
163  * LE_ERROR("Failed to accept install from AirVantage (%s)", LE_RESULT_TXT(res));
164  * }
165  * break;
166  *
167  * case LE_AVC_UNINSTALL_PENDING:
168  * LE_INFO("Accepting %s uninstall.", GetUpdateType());
169  * res = le_avc_AcceptUninstall();
170  * if (res != LE_OK)
171  * {
172  * LE_ERROR("Failed to accept uninstall from AirVantage (%s)", LE_RESULT_TXT(res));
173  * }
174  * break;
175  *
176  * case LE_AVC_REBOOT_PENDING:
177  * LE_INFO("Accepting device reboot.");
178  * res = le_avc_AcceptReboot();
179  * if (res != LE_OK)
180  * {
181  * LE_ERROR("Failed to accept reboot from AirVantage (%s)", LE_RESULT_TXT(res));
182  * }
183  * break;
184  *
185  * default:
186  * // No action required
187  * break;
188  * }
189  * @endcode
190  *
191  * @note Even if an App calls le_avc_AcceptInstall(), the install may still be blocked by another
192  * App using the @ref c_le_avc_update_app functions. To defer the decision, an App can use
193  * le_avc_DeferInstall() to defer the install for the specified number of minutes. After the defer
194  * time has elapsed, the pending install notification will be re-sent to allow Apps to make a new
195  * decision, or again defer.
196  *
197  * @subsubsection c_le_avc_updateControl_download_end Download and install processes
198  *
199  * When a package is fully downloaded from the AirVantage server, the device sends a specific
200  * message to the server to follow the update process.
201  * When the AirVantage server receives this message, it checks the download state and in case of
202  * success, it sends the install request to the device.
203  * If the user agreement for package install is activated, the @c LE_AVC_INSTALL_PENDING
204  * notification is sent. The user needs to accept it in order to launch the install process on
205  * device side.
206  * If the user agreement for package install is deactivated, the install process on device side
207  * is automatically launched.
208  * After accepting the install or when the install is automatic, the install process is launched 2
209  * seconds later by disconnecting the device from the AirVantage server if it's still connected and
210  * by launching the install process (device reboot).
211  *
212  * @subsubsection c_le_avc_updateControl_accepting Accepting Installs/Uninstalls
213  *
214  * Accepting an App install or uninstall will not initiate an AirVantage session if no session
215  * is active. An App should start an AirVantage session before accepting an App install/uninstall,
216  * to ensure the process is completed, and the server is updated.
217  *
218  * If no app has registered for notifications using le_avc_AddStatusEventHandler(),
219  * then any pending downloads and installs will happen automatically, subject to any restrictions
220  * imposed by app using the @ref c_le_avc_update_app functions.
221  *
222  * There is no restriction on the number of Apps registering for notifications.
223  *
224  * In case of any error incurred during App download/install, an error code will be set which can be
225  * retrieved by calling le_avc_GetErrorCode().
226  *
227  * @subsection c_le_avc_update_app Application Installation Blocking
228  *
229  * When an App is about to perform a critical operation, it can block the installation of
230  * an update with le_avc_BlockInstall(), and after it's finished with the critical operation, it
231  * can unblock the install with le_avc_UnblockInstall().
232  *
233  * What constitutes a critical operation depends on the App. An eCall App might
234  * block installs for the duration that it runs. A data collection App that wakes up
235  * once an hour might block installs while it collects and stores and/or transmits a new data
236  * sample, and then unblock installs just before it goes to sleep again.
237  *
238  * If an install can't be applied because it's blocked, another attempt to apply the install
239  * will be made at a later time.
240  *
241  * An App can add a session control handler using le_avc_AddSessionRequestEventHandler(). Requests
242  * by user Apps to open or close session will be forwarded to the session control handler. If no App
243  * has registered a session request handler, AVC session can be opened or closed anytime by
244  * user Apps.
245  *
246  * @subsection c_le_avc_suspend_resume Suspend and resume an update
247  *
248  * A firmware/application update can be interrupted or suspended by different events:
249  * - a device reboot
250  * - a network loss
251  * - a manual suspend through a session stopped by calling le_avc_StopSession() function
252  * - RAM issue
253  *
254  * After the update suspension, when the @c avcService is ready to resume the update process:
255  * - If the user agreements are disabled, the update process is automatically restarted.
256  * - If the user agreements are enabled, the previous @c PENDING notification is sent to the App,
257  * as indicated in the table below.
258  *
259  * | Last received event | Event sent to resume | Expected action from App |
260  * |--------------------------------|-------------------------------------------------------------|--------------------------|
261  * | @c LE_AVC_DOWNLOAD_PENDING | @c LE_AVC_DOWNLOAD_PENDING | Accept download |
262  * | @c LE_AVC_DOWNLOAD_IN_PROGRESS | @c LE_AVC_DOWNLOAD_PENDING with remaining bytes to download | Accept download |
263  * | @c LE_AVC_DOWNLOAD_COMPLETE | @c LE_AVC_DOWNLOAD_PENDING with zero bytes to download | Accept download |
264  * | @c LE_AVC_INSTALL_PENDING | @c LE_AVC_INSTALL_PENDING | Accept install |
265  * | @c LE_AVC_INSTALL_IN_PROGRESS | @c LE_AVC_INSTALL_PENDING | Accept install |
266  * | @c LE_AVC_UNINSTALL_PENDING | @c LE_AVC_UNINSTALL_PENDING | Accept uninstall |
267  * | @c LE_AVC_CONNECTION_PENDING | @c LE_AVC_CONNECTION_PENDING | Start session |
268  *
269  * @note
270  * - The @c avcService may not suspend the update process instantly (it typically takes a a few
271  * minutes). The @c PENDING notification will only be sent when the suspention is finished. Trying
272  * to resume the update process while a suspention is in progress will have no effect.
273  * - If firmware is updated (via fwupdate tool) or new legato is installed (via instlegato),
274  * all suspend/resume information stored by avcService is erased. So if developer updates firmware
275  * or legato (via ethernet or ecm etc.) in the middle of any update initiated by avcService, this
276  * need to be cancelled and restarted again from airVantage server.
277  *
278  * @subsubsection c_le_avc_suspend_resume_agreement Suspend/resume with activated user agreement
279  *
280  * When a user agreement for package download is activated and a download is suspended
281  * (@c LE_AVC_DOWNLOAD_PENDING notification is sent to registered apps), an app can get the download
282  * suspend reason by calling le_avc_GetErrorCode() and le_avc_GetHttpStatus() functions.
283  * If the download was suspended because of an app request or if the @c LE_AVC_DOWNLOAD_PENDING
284  * notification for the 1st time, the returned value by le_avc_GetErrorCode() function is
285  * @c LE_AVC_ERR_NONE.
286  *
287  * If the user agreement for package download is not activated
288  * - when a download is suspended by an app, the platform will automatically resume the download.
289  * - when a download is suspended because of network loss, the platform will automatically resume
290  * the download at next network registration.
291  *
292  * @subsection c_le_avc_update_failure Update failures
293  *
294  * A firmware/application update can fail if:
295  * - package URL is not valid
296  * - flash write issue
297  * - in case of delta package, the downloaded package could not be compliant with the current
298  * FW/App version
299  * - package is not certified sent by a trusted server
300  * - integrity check error
301  * - install/uninstall error
302  *
303  * The package URL is considered as invalid when folowing HTTP error codes are received when the
304  * package tries to be retrieved:
305  * - 404: Not found
306  * - 500: Internal Server Error
307  * - 501: Not Implemented
308  * - 505: HTTP version not supported
309  *
310  * | Failure reason | Related event | Function to be called to get more info |
311  * |-----------------------|----------------------------|----------------------------------------|
312  * | Invalid package URL | @c LE_AVC_DOWNLOAD_FAILED | le_avc_GetHttpStatus() |
313  * | Flash write error | @c LE_AVC_DOWNLOAD_FAILED | le_avc_GetErrorCode() |
314  * | Invalid delta package | @c LE_AVC_INSTALL_FAILED | |
315  * | integrity check error | @c LE_AVC_DOWNLOAD_FAILED | |
316  * | package not certified | @c LE_AVC_CERTIFICATION_KO | |
317  * | install error | @c LE_AVC_INSTALL_FAILED | |
318  * | uninstall error | @c LE_AVC_UNINSTALL_FAILED | |
319  *
320  * Example on checking the download failure reason:
321  * @code
322  * // In AVC event handler
323  * if (LE_AVC_DOWNLOAD_FAILED == updateStatus)
324  * {
325  * int avcError;
326  * int httpStatus;
327  *
328  * LE_INFO("Download failed");
329  *
330  * // Get the error cause
331  * avcError = le_avc_GetErrorCode();
332  * if (LE_AVC_ERR_NONE != avcError)
333  * {
334  * LE_WARN("Download failure %d", avcError);
335  * }
336  *
337  * // Get the HTTP status code
338  * httpStatus = le_avc_GetHttpStatus();
339  * if ((200 != httpStatus) && (206 != httpStatus))
340  * {
341  * LE_WARN("HTTP status code %d", httpStatus);
342  * }
343  * }
344  * @endcode
345  *
346  *
347  * @section c_le_avc_Timers Timers
348  *
349  * Polling timers sets the time that the Target will communicate with the AirVantage Server to check
350  * for new jobs. Retry timers will try and re-establish a connection to the AirVantage Server in
351  * accordance with the times that are declared.
352  *
353  * @subsection c_le_avc_PollingTimer Polling Timer
354  *
355  * The target will periodically initiate a connection to the AirVantage Server according to the
356  * settings for the polling timer to check if there are any pending jobs. The polling timer will
357  * initiate a session when it starts the count (at 0 minutes) and then again at the specified time
358  * set.
359  *
360  * To disable the polling timer call le_avc_SetPollingTimer() and set the value to 0.
361  *
362  * The polling timer accepts ranges from 0 to 525600 minutes. The polling timer does not get reset
363  * with reboots or power loss. If the target is powered off during the polling time, it will
364  * connect to the AVC Server upon startup of the app. For example, if the polling timer is set to 1
365  * hour then and the target reboots at the 20 minute mark, the polling timer will still initiate a
366  * connection at the 1 hour mark. If the target is powered off or in the middle of rebooting at the
367  * 1 hour mark, as soon as the app is started again, the polling timer will initiate a connection to
368  * the AirVantage Server.
369  *
370  * Polling timer initiated sessions will be disconnected after 20 seconds of inactivity. This does
371  * not apply to AirVantage sessions that have been initiated by an app. The app is responsible for
372  * disconnecting the session it initiates within a reasonable timeframe. Leaving the session open
373  * for long period will result in power wastage.
374  *
375  * To read the polling timer call: le_avc_GetPollingTimer()
376  *
377  * To write a new value to the polling timer call: le_avc_SetPollingTimer()
378  *
379  * Writing to the polling timer stops the current polling timer if it is running and starts a timer
380  * with the new value. The next connection will be initiated when the new polling timer reaches it's
381  * set value.
382  *
383  * @subsection c_le_avc_RetryTimers Retry Timers
384  *
385  * If an error occurs during a connection to the Device Services server (WWAN DATA establishment
386  * failed and an http error code is received) the embedded module will initiate a new connection
387  * according to the values defined in the retry timers.
388  *
389  * The timers are tried in sequence until a connection is established, or all enabled retry timers
390  * are exhausted. After all the enabled timers are exhausted, a new session must be initiated again
391  * by calling le_avc_startSession() after the expiry of the retry timer.
392  *
393  * The retry timer values are persistent (reboots and updates do not effect the retry timers).
394  * If you wish to disable a retry timer set the timer value
395  * to 0. You must always pass in at least 8 values to the retry timers.
396  *
397  * Retry timer values range from 0 to 20160 minutes.
398  * The function le_avc_GetRetryTimers() reads the retry timers in an array and the function
399  * le_avc_SetRetryTimers() writes the retry timers. When writing to the retry timers, values of
400  * all the 8 timers have to be defined.
401  *
402  * Example of calling retry timers, the session will be retried after 15 minutes, 1 hour, 4 hours,
403  * 8 hours, 1 day and 2 days, the last two retries are disabled:
404  * @code
405  * uint16_t RetryTimers[LE_AVC_NUM_RETRY_TIMERS] = {15, 60, 240, 480, 1440, 2880, 0, 0};
406  * le_avc_SetRetryTimers(RetryTimers, LE_AVC_NUM_RETRY_TIMERS);
407  * @endcode
408  *
409  * @section c_le_avc_reboot Device reboot
410  *
411  * The AirVantage server can request to reboot the device. If a reboot is requested a notification
412  * is sent to the registered Apps. The App can either accept the reboot with le_avc_AcceptReboot()
413  * or defer it for a specified number of minutes with le_avc_DeferReboot(). After the defer time
414  * has elapsed, the pending reboot notification will be re-sent. This allows the registered app to
415  * make a new decision or defer the reboot again.
416  *
417  * If no App has registered for notifications using le_avc_AddStatusEventHandler(), then
418  * any pending reboot will happen automatically.
419  *
420  * @section c_le_avc_GetCredentialStatus Credential Status
421  * The device is provisioned with bootstrap credentials from factory. The Device Management (DM)
422  * credentials are provisioned by AirVantage Bootstrap Server. This API is used to retrieve the
423  * status of credentials provisioned on the device.
424  *
425  * @section c_le_avc_connection Connection pending
426  *
427  * The AirVantage agent can request a connection to the AirVantage server, especially when a
428  * firmware package is installed (after a platform reboot) or device reboots in the middle of
429  * software update (after finishing software update on reboot). In this case a notification is
430  * sent to the control App, which can start the connection with le_avc_StartSession(). If
431  * the user agreement is enabled for the connection, and the user enabled the connection,
432  * the connection will not be automatically disconnected without explicit call to
433  * le_avc_StopSession()
434  *
435  * @section c_le_avc_routing Data routing
436  *
437  * By default the AirVantage connection uses the default mobile data profile and the default route
438  * set by the data connection service.
439  *
440  * If the user wishes to control the network configuration, e.g. to use the AirVantage agent with
441  * multi-PDP contexts, they should first bind the application to the data connection service:
442  * @verbatim
443  bindings:
444  {
445  clientExe.clientComponent.le_data -> dataConnectionService.le_data
446  }
447  @endverbatim
448  *
449  * The data connection service should then be configured before launching the AirVantage connection:
450  * - le_data_SetCellularProfileIndex() allows to change the data profile to use.
451  * - le_data_GetDefaultRouteStatus() indicates if the default route is activated in the data
452  * connection service. This default route can be deactivated in the data connection service
453  * configuration database, as explained in @ref c_le_data_defaultRoute. If the default route is
454  * deactivated, the AirVantage agent will automatically add routes to be able to reach the
455  * AirVantage server through the connection used by AirVantage.
456  *
457  * @section c_le_avc_timeout Connection / Download timeout
458  *
459  * The AirVantage connector service will abort FOTA/SOTA download, if it takes more than
460  * 300 seconds to establish a connection. Download will also be aborted, if the download speed is
461  * too low (less than 100 bytes /second) for too long (for more than 1000 seconds).
462  * These values are chosen based on experiments on low speed network. There is no configuration
463  * for these timeouts.
464  *
465  * @section le_avcService_configdb Service Configuration Tree
466  * @copydoc le_avcService_configdbPage_Hide
467  *
468  *
469  * Copyright (C) Sierra Wireless Inc.
470  */
471 /**
472  * @interface le_avcService_configdbPage_Hide
473  *
474  * The configuration database path for the activityTimeout is:
475  * @verbatim
476  /
477  apps/
478  avcService/
479  activityTimeout
480  @endverbatim
481  *
482  *
483  * After an AirVantage session is started, if there's no activity between the device and the server
484  * within the timer interval, then LE_AVC_NO_UPDATE state will be returned to the app. However,
485  * this activity timeout can be overridden by setting an integer value for
486  * /apps/avcService/activityTimeout. The activity timer is initialized only when the @c avcService
487  * starts. If a valid entry >0 is found, then it will be used instead of the default value of 20
488  * seconds. The following steps should be used to set the activityTimeout.
489  *
490  *
491  * @verbatim
492  config set /apps/avcService/activityTimeout xx int
493  app restart avcService
494  @endverbatim
495  *
496  * @note
497  * Everytime a new value is written to activityTimeout, the avcService needs to be
498  * restarted to read the new value.
499  *
500  *
501  */
502 /**
503  * @file le_avc_interface.h
504  *
505  * Legato @ref c_le_avc include file.
506  *
507  * Copyright (C) Sierra Wireless Inc.
508  */
509 
510 #ifndef LE_AVC_INTERFACE_H_INCLUDE_GUARD
511 #define LE_AVC_INTERFACE_H_INCLUDE_GUARD
512 
513 
514 #include "legato.h"
515 
516 // Interface specific includes
517 #include "le_limit_interface.h"
518 
519 // Internal includes for this interface
520 #include "le_avc_common.h"
521 //--------------------------------------------------------------------------------------------------
522 /**
523  * Type for handler called when a server disconnects.
524  */
525 //--------------------------------------------------------------------------------------------------
526 typedef void (*le_avc_DisconnectHandler_t)(void *);
527 
528 //--------------------------------------------------------------------------------------------------
529 /**
530  *
531  * Connect the current client thread to the service providing this API. Block until the service is
532  * available.
533  *
534  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
535  * called before any other functions in this API. Normally, ConnectService is automatically called
536  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
537  *
538  * This function is created automatically.
539  */
540 //--------------------------------------------------------------------------------------------------
542 (
543  void
544 );
545 
546 //--------------------------------------------------------------------------------------------------
547 /**
548  *
549  * Try to connect the current client thread to the service providing this API. Return with an error
550  * if the service is not available.
551  *
552  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
553  * called before any other functions in this API. Normally, ConnectService is automatically called
554  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
555  *
556  * This function is created automatically.
557  *
558  * @return
559  * - LE_OK if the client connected successfully to the service.
560  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
561  * bound.
562  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
563  * - LE_COMM_ERROR if the Service Directory cannot be reached.
564  */
565 //--------------------------------------------------------------------------------------------------
567 (
568  void
569 );
570 
571 //--------------------------------------------------------------------------------------------------
572 /**
573  * Set handler called when server disconnection is detected.
574  *
575  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
576  * to continue without exiting, it should call longjmp() from inside the handler.
577  */
578 //--------------------------------------------------------------------------------------------------
580 (
581  le_avc_DisconnectHandler_t disconnectHandler,
582  void *contextPtr
583 );
584 
585 //--------------------------------------------------------------------------------------------------
586 /**
587  *
588  * Disconnect the current client thread from the service providing this API.
589  *
590  * Normally, this function doesn't need to be called. After this function is called, there's no
591  * longer a connection to the service, and the functions in this API can't be used. For details, see
592  * @ref apiFilesC_client.
593  *
594  * This function is created automatically.
595  */
596 //--------------------------------------------------------------------------------------------------
598 (
599  void
600 );
601 
602 
603 //--------------------------------------------------------------------------------------------------
604 /**
605  * Status of session or update
606  *
607  * If an update is pending, it must first be downloaded and then installed.
608  */
609 //--------------------------------------------------------------------------------------------------
610 
611 
612 //--------------------------------------------------------------------------------------------------
613 /**
614  * Operations which require user agreement
615  */
616 //--------------------------------------------------------------------------------------------------
617 
618 
619 //--------------------------------------------------------------------------------------------------
620 /**
621  * Request to open or close avms session.
622  */
623 //--------------------------------------------------------------------------------------------------
624 
625 
626 //--------------------------------------------------------------------------------------------------
627 /**
628  * The type of pending update
629  */
630 //--------------------------------------------------------------------------------------------------
631 
632 
633 //--------------------------------------------------------------------------------------------------
634 /**
635  * Error code used to provide diagnostic information after a failure (includes both download and
636  * install failure).
637  *
638  * @note
639  * Additional information may also be available in the target device's system log.
640  */
641 //--------------------------------------------------------------------------------------------------
642 
643 
644 //--------------------------------------------------------------------------------------------------
645 /**
646  * Session type indicates whether the device is connected to the bootstrap server or the
647  * device management server.
648  */
649 //--------------------------------------------------------------------------------------------------
650 
651 
652 //--------------------------------------------------------------------------------------------------
653 /**
654  * Status of the device credentials
655  */
656 //--------------------------------------------------------------------------------------------------
657 
658 
659 //--------------------------------------------------------------------------------------------------
660 /**
661  * Handler for update availability status
662  */
663 //--------------------------------------------------------------------------------------------------
664 
665 
666 //--------------------------------------------------------------------------------------------------
667 /**
668  * Reference type used by Add/Remove functions for EVENT 'le_avc_StatusEvent'
669  */
670 //--------------------------------------------------------------------------------------------------
671 
672 
673 //--------------------------------------------------------------------------------------------------
674 /**
675  * Handler for receiving session open or close request.
676  */
677 //--------------------------------------------------------------------------------------------------
678 
679 
680 //--------------------------------------------------------------------------------------------------
681 /**
682  * Reference type used by Add/Remove functions for EVENT 'le_avc_SessionRequestEvent'
683  */
684 //--------------------------------------------------------------------------------------------------
685 
686 
687 //--------------------------------------------------------------------------------------------------
688 /**
689  * Handler for receiving communication information.
690  */
691 //--------------------------------------------------------------------------------------------------
692 
693 
694 //--------------------------------------------------------------------------------------------------
695 /**
696  * Reference type used by Add/Remove functions for EVENT 'le_avc_CommInfo'
697  */
698 //--------------------------------------------------------------------------------------------------
699 
700 
701 //--------------------------------------------------------------------------------------------------
702 /**
703  * Reference returned by BlockInstall function and used by UnblockInstall function
704  */
705 //--------------------------------------------------------------------------------------------------
706 
707 
708 //--------------------------------------------------------------------------------------------------
709 /**
710  * Add handler function for EVENT 'le_avc_StatusEvent'
711  *
712  * This event provides information on update availability status
713  */
714 //--------------------------------------------------------------------------------------------------
715 le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler
716 (
717  le_avc_StatusHandlerFunc_t handlerPtr,
718  ///< [IN]
719  void* contextPtr
720  ///< [IN]
721 );
722 
723 //--------------------------------------------------------------------------------------------------
724 /**
725  * Remove handler function for EVENT 'le_avc_StatusEvent'
726  */
727 //--------------------------------------------------------------------------------------------------
729 (
730  le_avc_StatusEventHandlerRef_t handlerRef
731  ///< [IN]
732 );
733 
734 //--------------------------------------------------------------------------------------------------
735 /**
736  * Add handler function for EVENT 'le_avc_SessionRequestEvent'
737  *
738  * This event provides information on session open or close request.
739  */
740 //--------------------------------------------------------------------------------------------------
741 le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler
742 (
743  le_avc_SessionRequestHandlerFunc_t handlerPtr,
744  ///< [IN]
745  void* contextPtr
746  ///< [IN]
747 );
748 
749 //--------------------------------------------------------------------------------------------------
750 /**
751  * Remove handler function for EVENT 'le_avc_SessionRequestEvent'
752  */
753 //--------------------------------------------------------------------------------------------------
755 (
756  le_avc_SessionRequestEventHandlerRef_t handlerRef
757  ///< [IN]
758 );
759 
760 //--------------------------------------------------------------------------------------------------
761 /**
762  * Add handler function for EVENT 'le_avc_CommInfo'
763  *
764  * This event provides communication errors.
765  */
766 //--------------------------------------------------------------------------------------------------
767 le_avc_CommInfoHandlerRef_t le_avc_AddCommInfoHandler
768 (
769  le_avc_CommInfoHandlerFunc_t handlerPtr,
770  ///< [IN]
771  void* contextPtr
772  ///< [IN]
773 );
774 
775 //--------------------------------------------------------------------------------------------------
776 /**
777  * Remove handler function for EVENT 'le_avc_CommInfo'
778  */
779 //--------------------------------------------------------------------------------------------------
781 (
782  le_avc_CommInfoHandlerRef_t handlerRef
783  ///< [IN]
784 );
785 
786 //--------------------------------------------------------------------------------------------------
787 /**
788  * Start a session with the AirVantage server
789  *
790  * This will cause a query to be sent to the server, for pending updates.
791  *
792  * @return
793  * - LE_OK if connection request has been sent.
794  * - LE_FAULT on failure
795  * - LE_DUPLICATE if already connected.
796  */
797 //--------------------------------------------------------------------------------------------------
799 (
800  void
801 );
802 
803 //--------------------------------------------------------------------------------------------------
804 /**
805  * Stop a session with the AirVantage server
806  *
807  * If a download is in progress and the user agreement is enabled, this suspends the download,
808  * otherwise if the user agreement is disabled, a new connection is automatically initiated in order
809  * to resume the download.
810  *
811  * @return
812  * - LE_OK on success
813  * - LE_FAULT on failure
814  * - LE_DUPLICATE if already disconnected
815  */
816 //--------------------------------------------------------------------------------------------------
818 (
819  void
820 );
821 
822 //--------------------------------------------------------------------------------------------------
823 /**
824  * Send a specific message to the server to be sure that the route between the device and the server
825  * is available.
826  * This API needs to be called when any package download is over (successfully or not) and before
827  * sending any notification on asset data to the server.
828  *
829  * @return
830  * - LE_OK when the treatment is launched
831  * - LE_FAULT on failure
832  * - LE_UNSUPPORTED when the API is not supported
833  *
834  */
835 //--------------------------------------------------------------------------------------------------
837 (
838  void
839 );
840 
841 //--------------------------------------------------------------------------------------------------
842 /**
843  * Defer the currently pending connection, for the given number of minutes
844  *
845  * @return
846  * - LE_OK on success
847  * - LE_FAULT on failure
848  */
849 //--------------------------------------------------------------------------------------------------
851 (
852  uint32_t deferMinutes
853  ///< [IN]
854 );
855 
856 //--------------------------------------------------------------------------------------------------
857 /**
858  * Accept the currently pending download
859  *
860  * @return
861  * - LE_OK on success
862  * - LE_FAULT on failure
863  */
864 //--------------------------------------------------------------------------------------------------
866 (
867  void
868 );
869 
870 //--------------------------------------------------------------------------------------------------
871 /**
872  * Defer the currently pending download, for the given number of minutes
873  *
874  * @return
875  * - LE_OK on success
876  * - LE_FAULT on failure
877  */
878 //--------------------------------------------------------------------------------------------------
880 (
881  uint32_t deferMinutes
882  ///< [IN]
883 );
884 
885 //--------------------------------------------------------------------------------------------------
886 /**
887  * Accept the currently pending install
888  *
889  * @return
890  * - LE_OK on success
891  * - LE_FAULT on failure
892  */
893 //--------------------------------------------------------------------------------------------------
895 (
896  void
897 );
898 
899 //--------------------------------------------------------------------------------------------------
900 /**
901  * Defer the currently pending install
902  *
903  * @return
904  * - LE_OK on success
905  * - LE_FAULT on failure
906  */
907 //--------------------------------------------------------------------------------------------------
909 (
910  uint32_t deferMinutes
911  ///< [IN]
912 );
913 
914 //--------------------------------------------------------------------------------------------------
915 /**
916  * Accept the currently pending uninstall
917  *
918  * @return
919  * - LE_OK on success
920  * - LE_FAULT on failure
921  */
922 //--------------------------------------------------------------------------------------------------
924 (
925  void
926 );
927 
928 //--------------------------------------------------------------------------------------------------
929 /**
930  * Defer the currently pending uninstall
931  *
932  * @return
933  * - LE_OK on success
934  * - LE_FAULT on failure
935  */
936 //--------------------------------------------------------------------------------------------------
938 (
939  uint32_t deferMinutes
940  ///< [IN]
941 );
942 
943 //--------------------------------------------------------------------------------------------------
944 /**
945  * Accept the currently pending reboot
946  *
947  * @note When this function is called, a 2-second timer is launched and the reboot function is
948  * called when the timer expires.
949  *
950  * @return
951  * - LE_OK on success
952  * - LE_FAULT on failure
953  */
954 //--------------------------------------------------------------------------------------------------
956 (
957  void
958 );
959 
960 //--------------------------------------------------------------------------------------------------
961 /**
962  * Defer the currently pending reboot
963  *
964  * @return
965  * - LE_OK on success
966  * - LE_FAULT on failure
967  */
968 //--------------------------------------------------------------------------------------------------
970 (
971  uint32_t deferMinutes
972  ///< [IN]
973 );
974 
975 //--------------------------------------------------------------------------------------------------
976 /**
977  * Get the update type of the currently pending update
978  *
979  * @return
980  * - LE_OK on success
981  * - LE_FAULT if not available
982  */
983 //--------------------------------------------------------------------------------------------------
985 (
986  le_avc_UpdateType_t* updateTypePtr
987  ///< [OUT]
988 );
989 
990 //--------------------------------------------------------------------------------------------------
991 /**
992  * Get the name for the currently pending app update
993  *
994  * @return
995  * - LE_OK on success
996  * - LE_FAULT if not available, or isn't APPL_UPDATE type
997  */
998 //--------------------------------------------------------------------------------------------------
1000 (
1001  char* updateName,
1002  ///< [OUT]
1003  size_t updateNameSize
1004  ///< [IN]
1005 );
1006 
1007 //--------------------------------------------------------------------------------------------------
1008 /**
1009  * Prevent any pending updates from being installed.
1010  *
1011  * @return
1012  * - Reference for block update request (to be used later for unblocking updates)
1013  * - NULL if the operation was not successful
1014  */
1015 //--------------------------------------------------------------------------------------------------
1016 le_avc_BlockRequestRef_t le_avc_BlockInstall
1017 (
1018  void
1019 );
1020 
1021 //--------------------------------------------------------------------------------------------------
1022 /**
1023  * Allow any pending updates to be installed
1024  */
1025 //--------------------------------------------------------------------------------------------------
1027 (
1028  le_avc_BlockRequestRef_t blockRef
1029  ///< [IN] block request ref returned by le_avc_BlockInstall
1030 );
1031 
1032 //--------------------------------------------------------------------------------------------------
1033 /**
1034  * Function to get error code when update fails.
1035  *
1036  * @return
1037  * - Error code of encountered error.
1038  * - ERR_NONE if update is in any other state.
1039  */
1040 //--------------------------------------------------------------------------------------------------
1041 le_avc_ErrorCode_t le_avc_GetErrorCode
1042 (
1043  void
1044 );
1045 
1046 //--------------------------------------------------------------------------------------------------
1047 /**
1048  * Function to read the current session type, or the last session type if there is no
1049  * active session.
1050  *
1051  * @return
1052  * - SessionType
1053  */
1054 //--------------------------------------------------------------------------------------------------
1055 le_avc_SessionType_t le_avc_GetSessionType
1056 (
1057  void
1058 );
1059 
1060 //--------------------------------------------------------------------------------------------------
1061 /**
1062  * Function to read the http status of the last download.
1063  *
1064  * @return
1065  * - HttpStatus as defined in RFC 7231, Section 6.
1066  */
1067 //--------------------------------------------------------------------------------------------------
1068 uint16_t le_avc_GetHttpStatus
1069 (
1070  void
1071 );
1072 
1073 //--------------------------------------------------------------------------------------------------
1074 /**
1075  * Function to read the polling timer.
1076  *
1077  * @return
1078  * - LE_OK on success
1079  * - LE_FAULT if not available
1080  * - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
1081  */
1082 //--------------------------------------------------------------------------------------------------
1084 (
1085  uint32_t* pollingTimerPtr
1086  ///< [OUT] Polling timer interval, minutes
1087 );
1088 
1089 //--------------------------------------------------------------------------------------------------
1090 /**
1091  * Function to read the retry timers.
1092  *
1093  * @return
1094  * - LE_OK on success.
1095  * - LE_FAULT if not able to read the timers.
1096  * - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
1097  */
1098 //--------------------------------------------------------------------------------------------------
1100 (
1101  uint16_t* timerValuePtr,
1102  ///< [OUT] Array of retry timer intervals, minutes.
1103  size_t* timerValueSizePtr
1104  ///< [INOUT]
1105 );
1106 
1107 //--------------------------------------------------------------------------------------------------
1108 /**
1109  * Function to read APN configuration.
1110  *
1111  * @return
1112  * - LE_OK on success.
1113  * - LE_FAULT if there is any error while reading.
1114  * - LE_OVERFLOW if the buffer provided is too small.
1115  */
1116 //--------------------------------------------------------------------------------------------------
1118 (
1119  char* apnName,
1120  ///< [OUT]
1121  size_t apnNameSize,
1122  ///< [IN]
1123  char* userName,
1124  ///< [OUT]
1125  size_t userNameSize,
1126  ///< [IN]
1127  char* userPwd,
1128  ///< [OUT]
1129  size_t userPwdSize
1130  ///< [IN]
1131 );
1132 
1133 //--------------------------------------------------------------------------------------------------
1134 /**
1135  * Function to write APN configuration.
1136  *
1137  * @return
1138  * - LE_OK on success.
1139  * - LE_OVERFLOW if one of the input strings is too long.
1140  */
1141 //--------------------------------------------------------------------------------------------------
1143 (
1144  const char* LE_NONNULL apnName,
1145  ///< [IN]
1146  const char* LE_NONNULL userName,
1147  ///< [IN]
1148  const char* LE_NONNULL userPwd
1149  ///< [IN]
1150 );
1151 
1152 //--------------------------------------------------------------------------------------------------
1153 /**
1154  * Function to set the polling timer.
1155  *
1156  * @return
1157  * - LE_OK on success.
1158  * - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
1159  */
1160 //--------------------------------------------------------------------------------------------------
1162 (
1163  uint32_t pollingTimer
1164  ///< [IN] Polling timer interval, minutes
1165 );
1166 
1167 //--------------------------------------------------------------------------------------------------
1168 /**
1169  * Function to set the retry timers.
1170  *
1171  * @return
1172  * - LE_OK on success.
1173  * - LE_FAULT if not able to set the timers.
1174  * - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
1175  */
1176 //--------------------------------------------------------------------------------------------------
1178 (
1179  const uint16_t* timerValuePtr,
1180  ///< [IN] Array of retry timer intervals, minutes.
1181  size_t timerValueSize
1182  ///< [IN]
1183 );
1184 
1185 //--------------------------------------------------------------------------------------------------
1186 /**
1187  * Function to retrieve status of the credentials provisioned on the device.
1188  *
1189  * @return
1190  * LE_AVC_NO_CREDENTIAL_PROVISIONED
1191  * - If neither Bootstrap nor Device Management credential is provisioned.
1192  * LE_AVC_BS_CREDENTIAL_PROVISIONED
1193  * - If Bootstrap credential is provisioned but Device Management credential is
1194  * not provisioned.
1195  * LE_AVC_DM_CREDENTIAL_PROVISIONED
1196  * - If Device management key is provisioned.
1197  */
1198 //--------------------------------------------------------------------------------------------------
1199 le_avc_CredentialStatus_t le_avc_GetCredentialStatus
1200 (
1201  void
1202 );
1203 
1204 //--------------------------------------------------------------------------------------------------
1205 /**
1206  * Function to set user agreements for download, install, reboot, connection and uninstall.
1207  *
1208  * @return
1209  * - LE_OK on success.
1210  * - LE_FAULT if failed to configure user agreement.
1211  */
1212 //--------------------------------------------------------------------------------------------------
1214 (
1215  le_avc_UserAgreement_t updateStatus,
1216  ///< [IN] Operation for which user agreements has to be set.
1217  bool enable
1218  ///< [IN] true = enable, false = disable.
1219 );
1220 
1221 //--------------------------------------------------------------------------------------------------
1222 /**
1223  * Function to get user agreements for download, install, reboot, connection and uninstall.
1224  *
1225  * @return
1226  * - LE_OK on success.
1227  * - LE_FAULT if failed to read user agreement state.
1228  */
1229 //--------------------------------------------------------------------------------------------------
1231 (
1232  le_avc_UserAgreement_t updateStatus,
1233  ///< [IN] Operation for which user agreements has to be read.
1234  bool* enablePtr
1235  ///< [OUT] true = enable, false = disable.
1236 );
1237 
1238 //--------------------------------------------------------------------------------------------------
1239 /**
1240  * Function to read a resource from a LWM2M object
1241  *
1242  * @return
1243  * - LE_OK on success.
1244  * - LE_FAULT if failed.
1245  * - LE_UNSUPPORTED if unsupported.
1246  */
1247 //--------------------------------------------------------------------------------------------------
1249 (
1250  uint16_t objectId,
1251  ///< [IN] Object identifier
1252  uint16_t objectInstanceId,
1253  ///< [IN] Object instance identifier
1254  uint16_t resourceId,
1255  ///< [IN] Resource identifier
1256  uint16_t resourceInstanceId,
1257  ///< [IN] Resource instance identifier
1258  char* data,
1259  ///< [OUT] String of requested resources to be read
1260  size_t dataSize
1261  ///< [IN]
1262 );
1263 
1264 #endif // LE_AVC_INTERFACE_H_INCLUDE_GUARD
void le_avc_RemoveSessionRequestEventHandler(le_avc_SessionRequestEventHandlerRef_t handlerRef)
le_result_t le_avc_GetPollingTimer(uint32_t *pollingTimerPtr)
LE_FULL_API void le_avc_SetServerDisconnectHandler(le_avc_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_avc_DeferReboot(uint32_t deferMinutes)
le_result_t le_avc_SetRetryTimers(const uint16_t *timerValuePtr, size_t timerValueSize)
le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler(le_avc_SessionRequestHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_avc_SetApnConfig(const char *LE_NONNULL apnName, const char *LE_NONNULL userName, const char *LE_NONNULL userPwd)
le_result_t le_avc_DeferConnect(uint32_t deferMinutes)
le_result_t
Definition: le_basics.h:45
le_avc_CommInfoHandlerRef_t le_avc_AddCommInfoHandler(le_avc_CommInfoHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_avc_AcceptReboot(void)
void le_avc_UnblockInstall(le_avc_BlockRequestRef_t blockRef)
le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler(le_avc_StatusHandlerFunc_t handlerPtr, void *contextPtr)
void le_avc_RemoveCommInfoHandler(le_avc_CommInfoHandlerRef_t handlerRef)
le_result_t le_avc_DeferUninstall(uint32_t deferMinutes)
le_result_t le_avc_AcceptUninstall(void)
le_result_t le_avc_GetUpdateType(le_avc_UpdateType_t *updateTypePtr)
void(* le_avc_DisconnectHandler_t)(void *)
Definition: le_avc_interface.h:526
le_result_t le_avc_StartSession(void)
le_result_t le_avc_StopSession(void)
void le_avc_RemoveStatusEventHandler(le_avc_StatusEventHandlerRef_t handlerRef)
le_result_t le_avc_GetUserAgreement(le_avc_UserAgreement_t updateStatus, bool *enablePtr)
le_result_t le_avc_AcceptDownload(void)
le_result_t le_avc_TryConnectService(void)
le_result_t le_avc_CheckRoute(void)
le_result_t le_avc_DeferInstall(uint32_t deferMinutes)
le_result_t le_avc_AcceptInstall(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_avc_BlockRequestRef_t le_avc_BlockInstall(void)
void le_avc_DisconnectService(void)
le_avc_SessionType_t le_avc_GetSessionType(void)
le_result_t le_avc_SetUserAgreement(le_avc_UserAgreement_t updateStatus, bool enable)
le_result_t le_avc_GetApnConfig(char *apnName, size_t apnNameSize, char *userName, size_t userNameSize, char *userPwd, size_t userPwdSize)
le_avc_CredentialStatus_t le_avc_GetCredentialStatus(void)
le_result_t le_avc_DeferDownload(uint32_t deferMinutes)
le_result_t le_avc_SetPollingTimer(uint32_t pollingTimer)
le_result_t le_avc_ReadLwm2mResource(uint16_t objectId, uint16_t objectInstanceId, uint16_t resourceId, uint16_t resourceInstanceId, char *data, size_t dataSize)
le_result_t le_avc_GetAppUpdateName(char *updateName, size_t updateNameSize)
le_result_t le_avc_GetRetryTimers(uint16_t *timerValuePtr, size_t *timerValueSizePtr)
uint16_t le_avc_GetHttpStatus(void)
le_avc_ErrorCode_t le_avc_GetErrorCode(void)
void le_avc_ConnectService(void)