le_avc_interface.h

    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 /** @addtogroup le_avc le_avc API Reference
  522  * @{
  523  * @file le_avc_common.h
  524  * @file le_avc_interface.h **/
  525 //--------------------------------------------------------------------------------------------------
  526 /**
  527  * Type for handler called when a server disconnects.
  528  */
  529 //--------------------------------------------------------------------------------------------------
  530 typedef void (*le_avc_DisconnectHandler_t)(void *);
  531 
  532 //--------------------------------------------------------------------------------------------------
  533 /**
  534  *
  535  * Connect the current client thread to the service providing this API. Block until the service is
  536  * available.
  537  *
  538  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  539  * called before any other functions in this API.  Normally, ConnectService is automatically called
  540  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  541  *
  542  * This function is created automatically.
  543  */
  544 //--------------------------------------------------------------------------------------------------
  545 void le_avc_ConnectService
  546 (
  547     void
  548 );
  549 
  550 //--------------------------------------------------------------------------------------------------
  551 /**
  552  *
  553  * Try to connect the current client thread to the service providing this API. Return with an error
  554  * if the service is not available.
  555  *
  556  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  557  * called before any other functions in this API.  Normally, ConnectService is automatically called
  558  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  559  *
  560  * This function is created automatically.
  561  *
  562  * @return
  563  *  - LE_OK if the client connected successfully to the service.
  564  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  565  *    bound.
  566  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  567  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  568  */
  569 //--------------------------------------------------------------------------------------------------
  570 le_result_t le_avc_TryConnectService
  571 (
  572     void
  573 );
  574 
  575 //--------------------------------------------------------------------------------------------------
  576 /**
  577  * Set handler called when server disconnection is detected.
  578  *
  579  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  580  * to continue without exiting, it should call longjmp() from inside the handler.
  581  */
  582 //--------------------------------------------------------------------------------------------------
  583 LE_FULL_API void le_avc_SetServerDisconnectHandler
  584 (
  585     le_avc_DisconnectHandler_t disconnectHandler,
  586     void *contextPtr
  587 );
  588 
  589 //--------------------------------------------------------------------------------------------------
  590 /**
  591  *
  592  * Disconnect the current client thread from the service providing this API.
  593  *
  594  * Normally, this function doesn't need to be called. After this function is called, there's no
  595  * longer a connection to the service, and the functions in this API can't be used. For details, see
  596  * @ref apiFilesC_client.
  597  *
  598  * This function is created automatically.
  599  */
  600 //--------------------------------------------------------------------------------------------------
  601 void le_avc_DisconnectService
  602 (
  603     void
  604 );
  605 
  606 
  607 //--------------------------------------------------------------------------------------------------
  608 /**
  609  * Status of session or update
  610  *
  611  * If an update is pending, it must first be downloaded and then installed.
  612  */
  613 //--------------------------------------------------------------------------------------------------
  614 
  615 
  616 //--------------------------------------------------------------------------------------------------
  617 /**
  618  * Operations which require user agreement
  619  */
  620 //--------------------------------------------------------------------------------------------------
  621 
  622 
  623 //--------------------------------------------------------------------------------------------------
  624 /**
  625  * Request to open or close avms session.
  626  */
  627 //--------------------------------------------------------------------------------------------------
  628 
  629 
  630 //--------------------------------------------------------------------------------------------------
  631 /**
  632  * The type of pending update
  633  */
  634 //--------------------------------------------------------------------------------------------------
  635 
  636 
  637 //--------------------------------------------------------------------------------------------------
  638 /**
  639  * Error code used to provide diagnostic information after a failure (includes both download and
  640  * install failure).
  641  *
  642  * @note
  643  *     Additional information may also be available in the target device's system log.
  644  */
  645 //--------------------------------------------------------------------------------------------------
  646 
  647 
  648 //--------------------------------------------------------------------------------------------------
  649 /**
  650  * Session type indicates whether the device is connected to the bootstrap server or the
  651  * device management server.
  652  */
  653 //--------------------------------------------------------------------------------------------------
  654 
  655 
  656 //--------------------------------------------------------------------------------------------------
  657 /**
  658  * Status of the device credentials
  659  */
  660 //--------------------------------------------------------------------------------------------------
  661 
  662 
  663 //--------------------------------------------------------------------------------------------------
  664 /**
  665  * Type of the configuration to pass to the API
  666  */
  667 //--------------------------------------------------------------------------------------------------
  668 
  669 
  670 //--------------------------------------------------------------------------------------------------
  671 /**
  672  * Handler for update availability status
  673  */
  674 //--------------------------------------------------------------------------------------------------
  675 
  676 
  677 //--------------------------------------------------------------------------------------------------
  678 /**
  679  * Reference type used by Add/Remove functions for EVENT 'le_avc_StatusEvent'
  680  */
  681 //--------------------------------------------------------------------------------------------------
  682 
  683 
  684 //--------------------------------------------------------------------------------------------------
  685 /**
  686  * Handler for receiving session open or close request.
  687  */
  688 //--------------------------------------------------------------------------------------------------
  689 
  690 
  691 //--------------------------------------------------------------------------------------------------
  692 /**
  693  * Reference type used by Add/Remove functions for EVENT 'le_avc_SessionRequestEvent'
  694  */
  695 //--------------------------------------------------------------------------------------------------
  696 
  697 
  698 //--------------------------------------------------------------------------------------------------
  699 /**
  700  * Handler for receiving communication information.
  701  */
  702 //--------------------------------------------------------------------------------------------------
  703 
  704 
  705 //--------------------------------------------------------------------------------------------------
  706 /**
  707  * Reference type used by Add/Remove functions for EVENT 'le_avc_CommInfo'
  708  */
  709 //--------------------------------------------------------------------------------------------------
  710 
  711 
  712 //--------------------------------------------------------------------------------------------------
  713 /**
  714  * Reference returned by BlockInstall function and used by UnblockInstall function
  715  */
  716 //--------------------------------------------------------------------------------------------------
  717 
  718 
  719 //--------------------------------------------------------------------------------------------------
  720 /**
  721  * Add handler function for EVENT 'le_avc_StatusEvent'
  722  *
  723  * This event provides information on update availability status
  724  */
  725 //--------------------------------------------------------------------------------------------------
  726 le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler
  727 (
  728     le_avc_StatusHandlerFunc_t handlerPtr,
  729         ///< [IN]
  730     void* contextPtr
  731         ///< [IN]
  732 );
  733 
  734 //--------------------------------------------------------------------------------------------------
  735 /**
  736  * Remove handler function for EVENT 'le_avc_StatusEvent'
  737  */
  738 //--------------------------------------------------------------------------------------------------
  739 void le_avc_RemoveStatusEventHandler
  740 (
  741     le_avc_StatusEventHandlerRef_t handlerRef
  742         ///< [IN]
  743 );
  744 
  745 //--------------------------------------------------------------------------------------------------
  746 /**
  747  * Add handler function for EVENT 'le_avc_SessionRequestEvent'
  748  *
  749  * This event provides information on session open or close request.
  750  */
  751 //--------------------------------------------------------------------------------------------------
  752 le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler
  753 (
  754     le_avc_SessionRequestHandlerFunc_t handlerPtr,
  755         ///< [IN]
  756     void* contextPtr
  757         ///< [IN]
  758 );
  759 
  760 //--------------------------------------------------------------------------------------------------
  761 /**
  762  * Remove handler function for EVENT 'le_avc_SessionRequestEvent'
  763  */
  764 //--------------------------------------------------------------------------------------------------
  765 void le_avc_RemoveSessionRequestEventHandler
  766 (
  767     le_avc_SessionRequestEventHandlerRef_t handlerRef
  768         ///< [IN]
  769 );
  770 
  771 //--------------------------------------------------------------------------------------------------
  772 /**
  773  * Add handler function for EVENT 'le_avc_CommInfo'
  774  *
  775  * This event provides communication errors.
  776  */
  777 //--------------------------------------------------------------------------------------------------
  778 le_avc_CommInfoHandlerRef_t le_avc_AddCommInfoHandler
  779 (
  780     le_avc_CommInfoHandlerFunc_t handlerPtr,
  781         ///< [IN]
  782     void* contextPtr
  783         ///< [IN]
  784 );
  785 
  786 //--------------------------------------------------------------------------------------------------
  787 /**
  788  * Remove handler function for EVENT 'le_avc_CommInfo'
  789  */
  790 //--------------------------------------------------------------------------------------------------
  791 void le_avc_RemoveCommInfoHandler
  792 (
  793     le_avc_CommInfoHandlerRef_t handlerRef
  794         ///< [IN]
  795 );
  796 
  797 //--------------------------------------------------------------------------------------------------
  798 /**
  799  * Start a session with the AirVantage server
  800  *
  801  * This will cause a query to be sent to the server, for pending updates.
  802  *
  803  * @return
  804  *      - LE_OK if connection request has been sent.
  805  *      - LE_FAULT on failure
  806  *      - LE_DUPLICATE if already connected.
  807  */
  808 //--------------------------------------------------------------------------------------------------
  809 le_result_t le_avc_StartSession
  810 (
  811     void
  812 );
  813 
  814 //--------------------------------------------------------------------------------------------------
  815 /**
  816  * Start a session with a specific Device Management (DM) server.
  817  *
  818  * This function is similar to le_avc_StartSession(), with the main difference of adding extra
  819  * parameter to specify the Server ID of the DM server; this way, it provides flexibility to
  820  * connect to any DM server, not just AirVantage.
  821  *
  822  * For example, the device may need to communicate with EDM server that is providing support
  823  * for the SIM Reachability features (LWM2M proprietory object 33408).
  824  *
  825  * Reserved Server IDs are:
  826  * 0 for Bootstrap server
  827  * 1 for AirVantage server
  828  * 1000 for EDM server
  829  *
  830  * @note DM servers may have different capabilities in terms of which LWM2M objects they support.
  831  * For instance, EDM server supports only one specific type of object (Object 33408), and does
  832  * not support Objects 5 and 9, which means it doesn't allow SOTA/FOTA operations.
  833  *
  834  * @note To initiate a session with AirVantage server, it's preferable to use le_avc_StartSession()
  835  * which exists specifically for this purpose.
  836  *
  837  * @note If the device doesn't have credentials for the specificed DM server, the boostrapping
  838  * process will be automatically initiated.
  839  *
  840  * @return
  841  *      - LE_OK if connection request has been sent.
  842  *      - LE_FAULT on failure
  843  *      - LE_DUPLICATE if already connected to the server.
  844  */
  845 //--------------------------------------------------------------------------------------------------
  846 le_result_t le_avc_StartDmSession
  847 (
  848     uint16_t serverId,
  849         ///< [IN] Short ID of the DM server. If equals to ALL_SERVERS, the
  850         ///<   session will be started with all available DM servers.
  851     bool isAutoDisconnect
  852         ///< [IN] Whether the session should be auto disconnected
  853 );
  854 
  855 //--------------------------------------------------------------------------------------------------
  856 /**
  857  * Stop a session with the DM server
  858  *
  859  * If a download is in progress and the user agreement is enabled, this suspends the download,
  860  * otherwise if the user agreement is disabled, a new connection is automatically initiated in order
  861  * to resume the download.
  862  *
  863  * @return
  864  *      - LE_OK on success
  865  *      - LE_FAULT on failure
  866  *      - LE_DUPLICATE if already disconnected
  867  */
  868 //--------------------------------------------------------------------------------------------------
  869 le_result_t le_avc_StopSession
  870 (
  871     void
  872 );
  873 
  874 //--------------------------------------------------------------------------------------------------
  875 /**
  876  * Send a specific message to the server to be sure that the route between the device and the server
  877  * is available.
  878  * This API needs to be called when any package download is over (successfully or not) and before
  879  * sending any notification on asset data to the server.
  880  *
  881  * @return
  882  *      - LE_OK when the treatment is launched
  883  *      - LE_FAULT on failure
  884  *      - LE_UNSUPPORTED when the API is not supported
  885  *
  886  */
  887 //--------------------------------------------------------------------------------------------------
  888 le_result_t le_avc_CheckRoute
  889 (
  890     void
  891 );
  892 
  893 //--------------------------------------------------------------------------------------------------
  894 /**
  895  * Defer the currently pending connection, for the given number of minutes
  896  *
  897  * @return
  898  *      - LE_OK on success
  899  *      - LE_FAULT on failure
  900  */
  901 //--------------------------------------------------------------------------------------------------
  902 le_result_t le_avc_DeferConnect
  903 (
  904     uint32_t deferMinutes
  905         ///< [IN]
  906 );
  907 
  908 //--------------------------------------------------------------------------------------------------
  909 /**
  910  * Accept the currently pending download
  911  *
  912  * @return
  913  *      - LE_OK on success
  914  *      - LE_FAULT on failure
  915  */
  916 //--------------------------------------------------------------------------------------------------
  917 le_result_t le_avc_AcceptDownload
  918 (
  919     void
  920 );
  921 
  922 //--------------------------------------------------------------------------------------------------
  923 /**
  924  * Defer the currently pending download, for the given number of minutes
  925  *
  926  * @return
  927  *      - LE_OK on success
  928  *      - LE_FAULT on failure
  929  */
  930 //--------------------------------------------------------------------------------------------------
  931 le_result_t le_avc_DeferDownload
  932 (
  933     uint32_t deferMinutes
  934         ///< [IN]
  935 );
  936 
  937 //--------------------------------------------------------------------------------------------------
  938 /**
  939  * Accept the currently pending install
  940  *
  941  * @return
  942  *      - LE_OK on success
  943  *      - LE_FAULT on failure
  944  */
  945 //--------------------------------------------------------------------------------------------------
  946 le_result_t le_avc_AcceptInstall
  947 (
  948     void
  949 );
  950 
  951 //--------------------------------------------------------------------------------------------------
  952 /**
  953  * Defer the currently pending install
  954  *
  955  * @return
  956  *      - LE_OK on success
  957  *      - LE_FAULT on failure
  958  */
  959 //--------------------------------------------------------------------------------------------------
  960 le_result_t le_avc_DeferInstall
  961 (
  962     uint32_t deferMinutes
  963         ///< [IN]
  964 );
  965 
  966 //--------------------------------------------------------------------------------------------------
  967 /**
  968  * Accept the currently pending uninstall
  969  *
  970  * @return
  971  *      - LE_OK on success
  972  *      - LE_FAULT on failure
  973  */
  974 //--------------------------------------------------------------------------------------------------
  975 le_result_t le_avc_AcceptUninstall
  976 (
  977     void
  978 );
  979 
  980 //--------------------------------------------------------------------------------------------------
  981 /**
  982  * Defer the currently pending uninstall
  983  *
  984  * @return
  985  *      - LE_OK on success
  986  *      - LE_FAULT on failure
  987  */
  988 //--------------------------------------------------------------------------------------------------
  989 le_result_t le_avc_DeferUninstall
  990 (
  991     uint32_t deferMinutes
  992         ///< [IN]
  993 );
  994 
  995 //--------------------------------------------------------------------------------------------------
  996 /**
  997  * Accept the currently pending reboot
  998  *
  999  * @note When this function is called, a 2-second timer is launched and the reboot function is
 1000  * called when the timer expires.
 1001  *
 1002  * @return
 1003  *      - LE_OK on success
 1004  *      - LE_FAULT on failure
 1005  */
 1006 //--------------------------------------------------------------------------------------------------
 1007 le_result_t le_avc_AcceptReboot
 1008 (
 1009     void
 1010 );
 1011 
 1012 //--------------------------------------------------------------------------------------------------
 1013 /**
 1014  * Defer the currently pending reboot
 1015  *
 1016  * @return
 1017  *      - LE_OK on success
 1018  *      - LE_FAULT on failure
 1019  */
 1020 //--------------------------------------------------------------------------------------------------
 1021 le_result_t le_avc_DeferReboot
 1022 (
 1023     uint32_t deferMinutes
 1024         ///< [IN]
 1025 );
 1026 
 1027 //--------------------------------------------------------------------------------------------------
 1028 /**
 1029  * Get the update type of the currently pending update
 1030  *
 1031  * @return
 1032  *      - LE_OK on success
 1033  *      - LE_FAULT if not available
 1034  */
 1035 //--------------------------------------------------------------------------------------------------
 1036 le_result_t le_avc_GetUpdateType
 1037 (
 1038     le_avc_UpdateType_t* updateTypePtr
 1039         ///< [OUT]
 1040 );
 1041 
 1042 //--------------------------------------------------------------------------------------------------
 1043 /**
 1044  * Get the name for the currently pending app update
 1045  *
 1046  * @return
 1047  *      - LE_OK on success
 1048  *      - LE_FAULT if not available, or isn't APPL_UPDATE type
 1049  */
 1050 //--------------------------------------------------------------------------------------------------
 1051 le_result_t le_avc_GetAppUpdateName
 1052 (
 1053     char* updateName,
 1054         ///< [OUT]
 1055     size_t updateNameSize
 1056         ///< [IN]
 1057 );
 1058 
 1059 //--------------------------------------------------------------------------------------------------
 1060 /**
 1061  * Prevent any pending updates from being installed.
 1062  *
 1063  * @return
 1064  *      - Reference for block update request (to be used later for unblocking updates)
 1065  *      - NULL if the operation was not successful
 1066  */
 1067 //--------------------------------------------------------------------------------------------------
 1068 le_avc_BlockRequestRef_t le_avc_BlockInstall
 1069 (
 1070     void
 1071 );
 1072 
 1073 //--------------------------------------------------------------------------------------------------
 1074 /**
 1075  * Allow any pending updates to be installed
 1076  */
 1077 //--------------------------------------------------------------------------------------------------
 1078 void le_avc_UnblockInstall
 1079 (
 1080     le_avc_BlockRequestRef_t blockRef
 1081         ///< [IN] block request ref returned by le_avc_BlockInstall
 1082 );
 1083 
 1084 //--------------------------------------------------------------------------------------------------
 1085 /**
 1086  * Function to get error code when update fails.
 1087  *
 1088  * @return
 1089  *      - Error code of encountered error.
 1090  *      - ERR_NONE if update is in any other state.
 1091  */
 1092 //--------------------------------------------------------------------------------------------------
 1093 le_avc_ErrorCode_t le_avc_GetErrorCode
 1094 (
 1095     void
 1096 );
 1097 
 1098 //--------------------------------------------------------------------------------------------------
 1099 /**
 1100  * Function to read the current session type, or the last session type if there is no
 1101  * active session.
 1102  *
 1103  * @return
 1104  *      - SessionType
 1105  */
 1106 //--------------------------------------------------------------------------------------------------
 1107 le_avc_SessionType_t le_avc_GetSessionType
 1108 (
 1109     void
 1110 );
 1111 
 1112 //--------------------------------------------------------------------------------------------------
 1113 /**
 1114  * Function to read the http status of the last download.
 1115  *
 1116  * @return
 1117  *      - HttpStatus as defined in RFC 7231, Section 6.
 1118  */
 1119 //--------------------------------------------------------------------------------------------------
 1120 uint16_t le_avc_GetHttpStatus
 1121 (
 1122     void
 1123 );
 1124 
 1125 //--------------------------------------------------------------------------------------------------
 1126 /**
 1127  * Function to read the polling timer.
 1128  *
 1129  * @return
 1130  *      - LE_OK on success
 1131  *      - LE_FAULT if not available
 1132  *      - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
 1133  */
 1134 //--------------------------------------------------------------------------------------------------
 1135 le_result_t le_avc_GetPollingTimer
 1136 (
 1137     uint32_t* pollingTimerPtr
 1138         ///< [OUT] Polling timer interval, minutes
 1139 );
 1140 
 1141 //--------------------------------------------------------------------------------------------------
 1142 /**
 1143  * Function to read the retry timers.
 1144  *
 1145  * @return
 1146  *      - LE_OK on success.
 1147  *      - LE_FAULT if not able to read the timers.
 1148  *      - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
 1149  */
 1150 //--------------------------------------------------------------------------------------------------
 1151 le_result_t le_avc_GetRetryTimers
 1152 (
 1153     uint16_t* timerValuePtr,
 1154         ///< [OUT] Array of retry timer intervals, minutes.
 1155     size_t* timerValueSizePtr
 1156         ///< [INOUT]
 1157 );
 1158 
 1159 //--------------------------------------------------------------------------------------------------
 1160 /**
 1161  * Function to read APN configuration.
 1162  *
 1163  * @return
 1164  *      - LE_OK on success.
 1165  *      - LE_FAULT if there is any error while reading.
 1166  *      - LE_OVERFLOW if the buffer provided is too small.
 1167  */
 1168 //--------------------------------------------------------------------------------------------------
 1169 le_result_t le_avc_GetApnConfig
 1170 (
 1171     char* apnName,
 1172         ///< [OUT]
 1173     size_t apnNameSize,
 1174         ///< [IN]
 1175     char* userName,
 1176         ///< [OUT]
 1177     size_t userNameSize,
 1178         ///< [IN]
 1179     char* userPwd,
 1180         ///< [OUT]
 1181     size_t userPwdSize
 1182         ///< [IN]
 1183 );
 1184 
 1185 //--------------------------------------------------------------------------------------------------
 1186 /**
 1187  * Function to write APN configuration.
 1188  *
 1189  * @return
 1190  *      - LE_OK on success.
 1191  *      - LE_OVERFLOW if one of the input strings is too long.
 1192  */
 1193 //--------------------------------------------------------------------------------------------------
 1194 le_result_t le_avc_SetApnConfig
 1195 (
 1196     const char* LE_NONNULL apnName,
 1197         ///< [IN]
 1198     const char* LE_NONNULL userName,
 1199         ///< [IN]
 1200     const char* LE_NONNULL userPwd
 1201         ///< [IN]
 1202 );
 1203 
 1204 //--------------------------------------------------------------------------------------------------
 1205 /**
 1206  * Function to set the polling timer to a value in minutes.
 1207  *
 1208  * @return
 1209  *      - LE_OK on success.
 1210  *      - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
 1211  */
 1212 //--------------------------------------------------------------------------------------------------
 1213 le_result_t le_avc_SetPollingTimer
 1214 (
 1215     uint32_t pollingTimer
 1216         ///< [IN] Polling timer interval, minutes
 1217 );
 1218 
 1219 //--------------------------------------------------------------------------------------------------
 1220 /**
 1221  * Function to set the retry timers.
 1222  *
 1223  * @return
 1224  *      - LE_OK on success.
 1225  *      - LE_FAULT if not able to set the timers.
 1226  *      - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
 1227  */
 1228 //--------------------------------------------------------------------------------------------------
 1229 le_result_t le_avc_SetRetryTimers
 1230 (
 1231     const uint16_t* timerValuePtr,
 1232         ///< [IN] Array of retry timer intervals, minutes.
 1233     size_t timerValueSize
 1234         ///< [IN]
 1235 );
 1236 
 1237 //--------------------------------------------------------------------------------------------------
 1238 /**
 1239  * Function to retrieve status of the credentials provisioned on the device.
 1240  *
 1241  * @return
 1242  *     LE_AVC_NO_CREDENTIAL_PROVISIONED
 1243  *          - If neither Bootstrap nor Device Management credential is provisioned.
 1244  *     LE_AVC_BS_CREDENTIAL_PROVISIONED
 1245  *          - If Bootstrap credential is provisioned but Device Management credential is
 1246  *              not provisioned.
 1247  *     LE_AVC_DM_CREDENTIAL_PROVISIONED
 1248  *          - If Device management key is provisioned.
 1249  */
 1250 //--------------------------------------------------------------------------------------------------
 1251 le_avc_CredentialStatus_t le_avc_GetCredentialStatus
 1252 (
 1253     void
 1254 );
 1255 
 1256 //--------------------------------------------------------------------------------------------------
 1257 /**
 1258  * Function to set user agreements for download, install, reboot, connection and uninstall.
 1259  *
 1260  * @return
 1261  *      - LE_OK on success.
 1262  *      - LE_FAULT if failed to configure user agreement.
 1263  */
 1264 //--------------------------------------------------------------------------------------------------
 1265 le_result_t le_avc_SetUserAgreement
 1266 (
 1267     le_avc_UserAgreement_t updateStatus,
 1268         ///< [IN] Operation for which user agreements has to be set.
 1269     bool enable
 1270         ///< [IN] true = enable, false = disable.
 1271 );
 1272 
 1273 //--------------------------------------------------------------------------------------------------
 1274 /**
 1275  * Function to get user agreements for download, install, reboot, connection and uninstall.
 1276  *
 1277  * @return
 1278  *      - LE_OK on success.
 1279  *      - LE_FAULT if failed to read user agreement state.
 1280  */
 1281 //--------------------------------------------------------------------------------------------------
 1282 le_result_t le_avc_GetUserAgreement
 1283 (
 1284     le_avc_UserAgreement_t updateStatus,
 1285         ///< [IN] Operation for which user agreements has to be read.
 1286     bool* enablePtr
 1287         ///< [OUT] true = enable, false = disable.
 1288 );
 1289 
 1290 //--------------------------------------------------------------------------------------------------
 1291 /**
 1292  * Function to read a resource from a LWM2M object
 1293  *
 1294  * @return
 1295  *      - LE_OK on success.
 1296  *      - LE_FAULT if failed.
 1297  *      - LE_UNSUPPORTED if unsupported.
 1298  */
 1299 //--------------------------------------------------------------------------------------------------
 1300 le_result_t le_avc_ReadLwm2mResource
 1301 (
 1302     uint16_t objectId,
 1303         ///< [IN] Object identifier
 1304     uint16_t objectInstanceId,
 1305         ///< [IN] Object instance identifier
 1306     uint16_t resourceId,
 1307         ///< [IN] Resource identifier
 1308     uint16_t resourceInstanceId,
 1309         ///< [IN] Resource instance identifier
 1310     char* data,
 1311         ///< [OUT] String of requested resources to be read
 1312     size_t dataSize
 1313         ///< [IN]
 1314 );
 1315 
 1316 //--------------------------------------------------------------------------------------------------
 1317 /**
 1318  * Function to set the NAT timeout
 1319  *
 1320  * This function sets the NAT timeout in volatile memory.
 1321  * When data need to be sent by the client, a check is made between this NAT timeout value and the
 1322  * time when last data were received from the server or sent to the server.
 1323  * If one of these times is greater than the NAT timeout, a DTLS resume is initiated.
 1324  * Default value if this function is not called: 40 seconds.
 1325  * Value 0 will deactivate any DTLS resume.
 1326  * This function can be called at any time.
 1327  */
 1328 //--------------------------------------------------------------------------------------------------
 1329 void le_avc_SetNatTimeout
 1330 (
 1331     uint32_t timeout
 1332         ///< [IN] Timeout (unit: seconds)
 1333 );
 1334 
 1335 //--------------------------------------------------------------------------------------------------
 1336 /**
 1337  * Check whether the session is started for a given Server Id.
 1338  *
 1339  * @return
 1340  *      - true if session is started
 1341  *      - false otherwise
 1342  */
 1343 //--------------------------------------------------------------------------------------------------
 1344 bool le_avc_IsSessionStarted
 1345 (
 1346     uint16_t serverId
 1347         ///< [IN] Short Server ID
 1348 );
 1349 
 1350 /** @} **/
 1351 
 1352 #endif // LE_AVC_INTERFACE_H_INCLUDE_GUARD
le_avc_SetPollingTimer
le_result_t le_avc_SetPollingTimer(uint32_t pollingTimer)
le_avc_StartSession
le_result_t le_avc_StartSession(void)
le_avc_DisconnectHandler_t
void(* le_avc_DisconnectHandler_t)(void *)
Definition: le_avc_interface.h:530
le_avc_GetErrorCode
le_avc_ErrorCode_t le_avc_GetErrorCode(void)
le_avc_GetPollingTimer
le_result_t le_avc_GetPollingTimer(uint32_t *pollingTimerPtr)
le_avc_common.h
le_avc_ErrorCode_t
le_avc_ErrorCode_t
Definition: le_avc_common.h:458
le_avc_AddStatusEventHandler
le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler(le_avc_StatusHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t
le_result_t
Definition: le_basics.h:46
le_avc_ReadLwm2mResource
le_result_t le_avc_ReadLwm2mResource(uint16_t objectId, uint16_t objectInstanceId, uint16_t resourceId, uint16_t resourceInstanceId, char *data, size_t dataSize)
le_avc_CredentialStatus_t
le_avc_CredentialStatus_t
Definition: le_avc_common.h:509
le_avc_CommInfoHandlerRef_t
struct le_avc_CommInfoHandler * le_avc_CommInfoHandlerRef_t
Definition: le_avc_common.h:557
le_avc_GetUserAgreement
le_result_t le_avc_GetUserAgreement(le_avc_UserAgreement_t updateStatus, bool *enablePtr)
le_avc_AddSessionRequestEventHandler
le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler(le_avc_SessionRequestHandlerFunc_t handlerPtr, void *contextPtr)
le_avc_DeferInstall
le_result_t le_avc_DeferInstall(uint32_t deferMinutes)
le_avc_GetApnConfig
le_result_t le_avc_GetApnConfig(char *apnName, size_t apnNameSize, char *userName, size_t userNameSize, char *userPwd, size_t userPwdSize)
le_avc_DeferUninstall
le_result_t le_avc_DeferUninstall(uint32_t deferMinutes)
le_avc_AcceptInstall
le_result_t le_avc_AcceptInstall(void)
le_avc_BlockInstall
le_avc_BlockRequestRef_t le_avc_BlockInstall(void)
le_avc_SetUserAgreement
le_result_t le_avc_SetUserAgreement(le_avc_UserAgreement_t updateStatus, bool enable)
le_avc_AddCommInfoHandler
le_avc_CommInfoHandlerRef_t le_avc_AddCommInfoHandler(le_avc_CommInfoHandlerFunc_t handlerPtr, void *contextPtr)
le_avc_CommInfoHandlerFunc_t
void(* le_avc_CommInfoHandlerFunc_t)(uint8_t code, const char *LE_NONNULL str, void *contextPtr)
Definition: le_avc_common.h:610
le_avc_SetNatTimeout
void le_avc_SetNatTimeout(uint32_t timeout)
le_avc_GetHttpStatus
uint16_t le_avc_GetHttpStatus(void)
le_avc_DeferConnect
le_result_t le_avc_DeferConnect(uint32_t deferMinutes)
le_avc_IsSessionStarted
bool le_avc_IsSessionStarted(uint16_t serverId)
le_avc_SetApnConfig
le_result_t le_avc_SetApnConfig(const char *LE_NONNULL apnName, const char *LE_NONNULL userName, const char *LE_NONNULL userPwd)
le_avc_TryConnectService
le_result_t le_avc_TryConnectService(void)
le_avc_AcceptUninstall
le_result_t le_avc_AcceptUninstall(void)
le_avc_GetUpdateType
le_result_t le_avc_GetUpdateType(le_avc_UpdateType_t *updateTypePtr)
le_avc_GetAppUpdateName
le_result_t le_avc_GetAppUpdateName(char *updateName, size_t updateNameSize)
le_avc_ConnectService
void le_avc_ConnectService(void)
le_limit_interface.h
le_avc_UnblockInstall
void le_avc_UnblockInstall(le_avc_BlockRequestRef_t blockRef)
le_avc_BlockRequestRef_t
struct le_avc_BlockRequest * le_avc_BlockRequestRef_t
Definition: le_avc_common.h:565
le_avc_SetRetryTimers
le_result_t le_avc_SetRetryTimers(const uint16_t *timerValuePtr, size_t timerValueSize)
le_avc_GetRetryTimers
le_result_t le_avc_GetRetryTimers(uint16_t *timerValuePtr, size_t *timerValueSizePtr)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_avc_SessionType_t
le_avc_SessionType_t
Definition: le_avc_common.h:492
le_avc_DisconnectService
void le_avc_DisconnectService(void)
legato.h
le_avc_StatusHandlerFunc_t
void(* le_avc_StatusHandlerFunc_t)(le_avc_Status_t updateStatus, int32_t totalNumBytes, int32_t progress, void *contextPtr)
Definition: le_avc_common.h:574
le_avc_DeferDownload
le_result_t le_avc_DeferDownload(uint32_t deferMinutes)
le_avc_SessionRequestHandlerFunc_t
void(* le_avc_SessionRequestHandlerFunc_t)(le_avc_SessionRequest_t request, void *contextPtr)
Definition: le_avc_common.h:597
le_avc_UpdateType_t
le_avc_UpdateType_t
Definition: le_avc_common.h:435
le_avc_SessionRequestEventHandlerRef_t
struct le_avc_SessionRequestEventHandler * le_avc_SessionRequestEventHandlerRef_t
Definition: le_avc_common.h:549
le_avc_RemoveStatusEventHandler
void le_avc_RemoveStatusEventHandler(le_avc_StatusEventHandlerRef_t handlerRef)
le_avc_StatusEventHandlerRef_t
struct le_avc_StatusEventHandler * le_avc_StatusEventHandlerRef_t
Definition: le_avc_common.h:541
le_avc_AcceptDownload
le_result_t le_avc_AcceptDownload(void)
le_avc_RemoveCommInfoHandler
void le_avc_RemoveCommInfoHandler(le_avc_CommInfoHandlerRef_t handlerRef)
le_avc_RemoveSessionRequestEventHandler
void le_avc_RemoveSessionRequestEventHandler(le_avc_SessionRequestEventHandlerRef_t handlerRef)
le_avc_StartDmSession
le_result_t le_avc_StartDmSession(uint16_t serverId, bool isAutoDisconnect)
le_avc_GetCredentialStatus
le_avc_CredentialStatus_t le_avc_GetCredentialStatus(void)
le_avc_StopSession
le_result_t le_avc_StopSession(void)
le_avc_AcceptReboot
le_result_t le_avc_AcceptReboot(void)
le_avc_SetServerDisconnectHandler
LE_FULL_API void le_avc_SetServerDisconnectHandler(le_avc_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_avc_GetSessionType
le_avc_SessionType_t le_avc_GetSessionType(void)
le_avc_CheckRoute
le_result_t le_avc_CheckRoute(void)
le_avc_DeferReboot
le_result_t le_avc_DeferReboot(uint32_t deferMinutes)
le_avc_UserAgreement_t
le_avc_UserAgreement_t
Definition: le_avc_common.h:399