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  * When writing a control app for the AirVantage Service it is up to the developer to ensure that
   35  * user agreements have been enabled for all actions the control app performs.  By default all
   36  * user agreements are enabled except for LE_AVC_CONNECTION_PENDING and the avcService app will
   37  * notify the control app and wait for a response before downloading or installing the update.
   38  * If the avcService can't communicate with the control app it waits for 3 minutes and tries again.
   39  * To not have the avcService wait for the control app to accept the agreement the user agreement
   40  * must be disabled.
   41  *
   42  * There are 5 events that require user agreements:
   43  * - LE_AVC_CONNECTION_PENDING
   44  * - LE_AVC_DOWNLOAD_PENDING
   45  * - LE_AVC_INSTALL_PENDING
   46  * - LE_AVC_REBOOT_PENDING
   47  * - LE_AVC_UNINSTALL_PENDING
   48  *
   49  * An app can respond to these user agreement notification by opening a connection if the
   50  * notification is connection pending or by accepting or deferring the operation if the notification
   51  * is one of download, install, uninstall or reboot pending.
   52  *
   53  * Whether avcService should forward these notifications to an app or act on these notifications by
   54  * itself is determined by the individual configuration flags that enables or disables user
   55  * agreement for these operations. If the user agreement flag is turned off for an operation,
   56  * the default action by avcService is to automatically accept that pending operation. An app can
   57  * register its handler by calling le_avc_AddStatusEventHandler() described in
   58  * c_le_avc_update_control and the configuration flags can be set by le_avc_SetUserAgreement().
   59  *
   60  * Example of enabling user agreement for LE_AVC_DOWNLOAD_PENDING:
   61  * @code
   62  *        le_result_t result;
   63  *        result = le_avc_SetUserAgreement(LE_AVC_USER_AGREEMENT_DOWNLOAD, true);
   64  *
   65  *        if (result != LE_OK)
   66  *        {
   67  *            LE_ERROR("Failed to enable user agreement for download operation");
   68  *        }
   69  * @endcode
   70  *
   71  * @subsection c_le_avc_update_control Update Control
   72  *
   73  * Any App can start a session with an AirVantage server to determine if there
   74  * is a pending update. This is done with le_avc_StartSession().
   75  *
   76  * The current session can be stopped using le_avc_StopSession(). This cancels any query for pending
   77  * update, or suspends a download in progress; however, it <b>won't stop</b> an install in progress.
   78  *
   79  * The status of a pending update is sent to all Apps registered for receiving a notification.
   80  * An App can use le_avc_AddStatusEventHandler() to register a handler function to
   81  * receive this notification. The notification will be received after a session is started.
   82  *
   83  * Example of registering an AVC handler and starting a session with fault checking:
   84  * @code
   85  *    // Start AVC Session
   86  *    LE_INFO("AirVantage Connection Controller started.");
   87  *    le_avc_AddStatusEventHandler(avcStatusHandler, NULL);    //register a AVC handler
   88  *
   89  *    //Start AVC session. Note: AVC handler must be registered prior starting a session
   90  *    le_result_t result = le_avc_StartSession();
   91  *    if (LE_FAULT == result)
   92  *    {
   93  *        le_avc_StopSession();
   94  *        le_avc_StartSession();
   95  *    }
   96  * @endcode
   97  *
   98  * An App can use le_avc_AddCommInfoHandler() to register a handler function and receive
   99  * communication information notifications. This function returns a reference. To unregister
  100  * the handler, le_avc_RemoveCommInfoHandler() should be called with the previously returned
  101  * reference.
  102  *
  103  *
  104  * Sometimes, @c avcService may decide to start a session with the AirVantage
  105  * server; for instance if a call to le_avc_AcceptDownload() when the session is stopped,
  106  * @c avcService will open a session to proceed with the download. In this case, a session started
  107  * notification could also be received, even if le_avc_StartSession() is not called explicitly.
  108  *
  109  * @subsubsection c_le_avc_updateControl_pending Pending Updates
  110  *
  111  * There can only be one pending update at a time.  To query the type of update, use
  112  * le_avc_GetUpdateType().  App updates can call le_avc_GetAppUpdateName() to retrieve the App name.
  113  *
  114  * If a download is pending, le_avc_AcceptDownload() can be used to allow the update to be
  115  * downloaded. An AirVantage session will be initiated if this api is called while there is no
  116  * active AirVantage session. le_avc_DeferDownload() can be used to defer the download for the
  117  * specified number of minutes. After the defer time has elapsed, the pending download notification
  118  * will be re-sent again to all registered apps. le_avc_AcceptDownload() can be used to accept the
  119  * download even before the defer timer expires. This behaviour is true for deferring install
  120  * and uninstall as well.
  121  *
  122  * Once an update has been downloaded, a new notification will be received to indicate that an
  123  * install is pending. Apps can then use le_avc_AcceptInstall() to allow the install to proceed.
  124  *
  125  * If an uninstall is pending, then le_avc_AcceptUninstall() can be used to allow the uninstall to
  126  * proceed. To defer the decision, le_avc_DeferUninstall() can be used to defer the uninstall for
  127  * the specified number of minutes. In case of an upgrade, the existing application will not be
  128  * uninstalled after le_avc_AcceptUninstall() is called. le_avc_AcceptUninstall() is only used to
  129  * signal the server to start downloading the new application. To proceed with an upgrade process,
  130  * accept the uninstall of the existing version followed by accepting the download and install of
  131  * the new version.
  132  *
  133  * @code
  134  *   switch (updateStatus)
  135  *        {
  136  *            case LE_AVC_DOWNLOAD_PENDING:
  137  *                LE_INFO("Accepting %s update.", GetUpdateType());
  138  *                res = le_avc_AcceptDownload();
  139  *                if (res != LE_OK)
  140  *                {
  141  *                    LE_ERROR("Failed to accept download from AirVantage (%s)", LE_RESULT_TXT(res));
  142  *                }
  143  *                break;
  144  *
  145  *            case LE_AVC_INSTALL_PENDING:
  146  *                LE_INFO("Accepting %s installation.", GetUpdateType());
  147  *                res = le_avc_AcceptInstall();
  148  *                if (res != LE_OK)
  149  *                {
  150  *                    LE_ERROR("Failed to accept install from AirVantage (%s)", LE_RESULT_TXT(res));
  151  *                }
  152  *                break;
  153  *
  154  *            case LE_AVC_UNINSTALL_PENDING:
  155  *                LE_INFO("Accepting %s uninstall.", GetUpdateType());
  156  *                res = le_avc_AcceptUninstall();
  157  *                if (res != LE_OK)
  158  *                {
  159  *                    LE_ERROR("Failed to accept uninstall from AirVantage (%s)", LE_RESULT_TXT(res));
  160  *                }
  161  *                break;
  162  *
  163  *            case LE_AVC_REBOOT_PENDING:
  164  *                LE_INFO("Accepting device reboot.");
  165  *                res = le_avc_AcceptReboot();
  166  *                if (res != LE_OK)
  167  *                {
  168  *                    LE_ERROR("Failed to accept reboot from AirVantage (%s)", LE_RESULT_TXT(res));
  169  *                }
  170  *                break;
  171  *
  172  *            default:
  173  *                // No action required
  174  *                break;
  175  *        }
  176  * @endcode
  177  *
  178  * @note Even if an App calls le_avc_AcceptInstall(), the install may still be blocked by another
  179  * App using the @ref c_le_avc_update_app functions. To defer the decision, an App can use
  180  * le_avc_DeferInstall() to defer the install for the specified number of minutes. After the defer
  181  * time has elapsed, the pending install notification will be re-sent to allow Apps to make a new
  182  * decision, or again defer.
  183  *
  184  *
  185  * @subsubsection c_le_avc_updateControl_accepting Accepting Installs/Uninstalls
  186  *
  187  * Accepting an App install or uninstall will not initiate an AirVantage session if no session
  188  * is active.  An App should start an AirVantage session before accepting an App install/uninstall,
  189  * to ensure the process is completed, and the server is updated.
  190  *
  191  * If no app has registered for notifications using le_avc_AddStatusEventHandler(),
  192  * then any pending downloads and installs will happen automatically, subject to any restrictions
  193  * imposed by app using the @ref c_le_avc_update_app functions.
  194  *
  195  * There is no restriction on the number of Apps registering for notifications.
  196  *
  197  * In case of any error incurred during App download/install, an error code will be set which can be
  198  * retrieved by calling le_avc_GetErrorCode().
  199  *
  200  * @subsection c_le_avc_update_app Application Installation Blocking
  201  *
  202  * When an App is about to perform a critical operation, it can block the installation of
  203  * an update with le_avc_BlockInstall(), and after it's finished with the critical operation, it
  204  * can unblock the install with le_avc_UnblockInstall().
  205  *
  206  * What constitutes a critical operation depends on the App.  An eCall App might
  207  * block installs for the duration that it runs.  A data collection App that wakes up
  208  * once an hour might block installs while it collects and stores and/or transmits a new data
  209  * sample, and then unblock installs just before it goes to sleep again.
  210  *
  211  * If an install can't be applied because it's blocked, another attempt to apply the install
  212  * will be made at a later time.
  213  *
  214  * An App can add a session control handler using le_avc_AddSessionRequestEventHandler(). Requests
  215  * by user Apps to open or close session will be forwarded to the session control handler. If no App
  216  * has registered a session request handler, AVC session can be opened or closed anytime by
  217  * user Apps.
  218  *
  219  * @subsection c_le_avc_suspend_resume Suspend and resume an update
  220  *
  221  * A firmware/application update can be interrupted or suspended by different events:
  222  * - a device reboot
  223  * - a network loss
  224  * - a manual suspend through a session stop.
  225  *
  226  * After the update suspension, when the @c avcService is ready to resume the update process:
  227  * - If the user agreements are disabled, the update process is automatically restarted.
  228  * - If the user agreements are enabled, the previous @c PENDING notification is sent to the App,
  229  * as indicated in the table below.
  230  *
  231  * @note The @c avcService might take a while to suspend the update process (typically a few
  232  * minutes), e.g. in some cases of firmware update. The @c PENDING notification will therefore be
  233  * sent only when the suspension is over. Trying to resume the update process while the suspension
  234  * is not over and the notification is not received has no effect.
  235  *
  236  * | Last received event            | Event sent to resume                                        | Expected action from App |
  237  * |--------------------------------|-------------------------------------------------------------|--------------------------|
  238  * | @c LE_AVC_DOWNLOAD_PENDING     | @c LE_AVC_DOWNLOAD_PENDING                                  | Accept download          |
  239  * | @c LE_AVC_DOWNLOAD_IN_PROGRESS | @c LE_AVC_DOWNLOAD_PENDING with remaining bytes to download | Accept download          |
  240  * | @c LE_AVC_DOWNLOAD_COMPLETE    | @c LE_AVC_DOWNLOAD_PENDING with zero bytes to download      | Accept download          |
  241  * | @c LE_AVC_INSTALL_PENDING      | @c LE_AVC_INSTALL_PENDING                                   | Accept install           |
  242  * | @c LE_AVC_INSTALL_IN_PROGRESS  | @c LE_AVC_INSTALL_PENDING                                   | Accept install           |
  243  * | @c LE_AVC_UNINSTALL_PENDING    | @c LE_AVC_UNINSTALL_PENDING                                 | Accept uninstall         |
  244  * | @c LE_AVC_CONNECTION_PENDING   | @c LE_AVC_CONNECTION_PENDING                                | Start session            |
  245  *
  246  * @note If firmware is updated (via fwupdate tool) or new legato is installed (via instlegato),
  247  * all suspend/resume information stored by avcService is erased. So if developer updates firmware
  248  * or legato (via ethernet or ecm etc.) in the middle of any update initiated by avcService, this
  249  * need to be cancelled and restarted again from airVantage server.
  250  *
  251  * @section c_le_avc_Timers Timers
  252  *
  253  * Polling timers sets the time that the Target will communicate with the AirVantage Server to check
  254  * for new jobs.  Retry timers will try and re-establish a connection to the AirVantage Server in
  255  * accordance with the times that are declared.
  256  *
  257  * @subsection c_le_avc_PollingTimer Polling Timer
  258  *
  259  * The target will periodically initiate a connection to the AirVantage Server according to the
  260  * settings for the polling timer to check if there are any pending jobs.  The polling timer will
  261  * initiate a session when it starts the count (at 0 minutes) and then again at the specified time
  262  * set.
  263  *
  264  * To disable the polling timer call le_avc_SetPollingTimer() and set the value to 0.
  265  *
  266  * The polling timer accepts ranges from 0 to 525600 minutes.  The polling timer does not get reset
  267  * with reboots or power loss.  If the target is powered off during the polling time, it will
  268  * connect to the AVC Server upon startup of the app.  For example, if the polling timer is set to 1
  269  * hour then and the target reboots at the 20 minute mark, the polling timer will still initiate a
  270  * connection at the 1 hour mark.  If the target is powered off or in the middle of rebooting at the
  271  * 1 hour mark, as soon as the app is started again, the polling timer will initiate a connection to
  272  * the AirVantage Server.
  273  *
  274  * Polling timer initiated sessions will be disconnected after 20 seconds of inactivity. This does
  275  * not apply to AirVantage sessions that have been initiated by an app. The app is responsible for
  276  * disconnecting the session it initiates within a reasonable timeframe. Leaving the session open
  277  * for long period will result in power wastage.
  278  *
  279  * To read the polling timer call: le_avc_GetPollingTimer()
  280  *
  281  * To write a new value to the polling timer call: le_avc_SetPollingTimer()
  282  *
  283  * Writing to the polling timer stops the current polling timer if it is running and starts a timer
  284  * with the new value. The next connection will be initiated when the new polling timer reaches it's
  285  * set value.
  286  *
  287  * @subsection c_le_avc_RetryTimers Retry Timers
  288  *
  289  * If an error occurs during a connection to the Device Services server (WWAN DATA establishment
  290  * failed and an http error code is received) the embedded module will initiate a new connection
  291  * according to the values defined in the retry timers.
  292  *
  293  * The timers are tried in sequence until a connection is established, or all enabled retry timers
  294  * are exhausted. After all the enabled timers are exhausted, a new session must be initiated again
  295  * by calling le_avc_startSession() after the expiry of the retry timer.
  296  *
  297  * The retry timer values are persistent (reboots and updates do not effect the retry timers).
  298  * If you wish to disable a retry timer set the timer value
  299  * to 0.  You must always pass in at least 8 values to the retry timers.
  300  *
  301  * Retry timer values range from 0 to 20160 minutes.
  302  * The function le_avc_GetRetryTimers() reads the retry timers in an array and the function
  303  * le_avc_SetRetryTimers() writes the retry timers. When writing to the retry timers, values of
  304  * all the 8 timers have to be defined.
  305  *
  306  * Example of calling retry timers, the session will be retried after 15 minutes, 1 hour, 4 hours,
  307  * 8 hours, 1 day and 2 days, the last two retries are disabled:
  308  * @code
  309  *   uint16_t RetryTimers[LE_AVC_NUM_RETRY_TIMERS] = {15, 60, 240, 480, 1440, 2880, 0, 0};
  310  *   le_avc_SetRetryTimers(RetryTimers, LE_AVC_NUM_RETRY_TIMERS);
  311  * @endcode
  312  *
  313  * @section c_le_avc_reboot Device reboot
  314  *
  315  * The AirVantage server can request to reboot the device. If a reboot is requested a notification
  316  * is sent to the registered Apps. The App can either accept the reboot with le_avc_AcceptReboot()
  317  * or defer it for a specified number of minutes with le_avc_DeferReboot(). After the defer time
  318  * has elapsed, the pending reboot notification will be re-sent. This allows the registered app to
  319  * make a new decision or defer the reboot again.
  320  *
  321  * If no App has registered for notifications using le_avc_AddStatusEventHandler(), then
  322  * any pending reboot will happen automatically.
  323  *
  324  * @section c_le_avc_GetCredentialStatus Credential Status
  325  * The device is provisioned with bootstrap credentials from factory. The Device Management (DM)
  326  * credentials are provisioned by AirVantage Bootstrap Server. This API is used to retrieve the
  327  * status of credentials provisioned on the device.
  328  *
  329  * @section c_le_avc_connection Connection pending
  330  *
  331  * The AirVantage agent can request a connection to the AirVantage server, especially when a
  332  * firmware package is installed (after a platform reboot) or device reboots in the middle of
  333  * software update (after finishing software update on reboot). In this case a notification is sent
  334  * to the control App, which can start the connection with le_avc_StartSession().
  335  *
  336  * @section c_le_avc_routing Data routing
  337  *
  338  * By default the AirVantage connection uses the default mobile data profile and the default route
  339  * set by the data connection service.
  340  *
  341  * If the user wishes to control the network configuration, e.g. to use the AirVantage agent with
  342  * multi-PDP contexts, they should first bind the application to the data connection service:
  343  * @verbatim
  344    bindings:
  345    {
  346       clientExe.clientComponent.le_data -> dataConnectionService.le_data
  347    }
  348    @endverbatim
  349  *
  350  * The data connection service should then be configured before launching the AirVantage connection:
  351  * - le_data_SetCellularProfileIndex() allows to change the data profile to use.
  352  * - le_data_GetDefaultRouteStatus() indicates if the default route is activated in the data
  353  * connection service. This default route can be deactivated in the data connection service
  354  * configuration database, as explained in @ref c_le_data_defaultRoute. If the default route is
  355  * deactivated, the AirVantage agent will automatically add routes to be able to reach the
  356  * AirVantage server through the connection used by AirVantage.
  357  *
  358  * @section c_le_avc_timeout Connection / Download timeout
  359  *
  360  * The AirVantage connector service will abort FOTA/SOTA download, if it takes more than
  361  * 300 seconds to establish a connection. Download will also be aborted, if the download speed is
  362  * too low (less than 100 bytes /second) for too long (for more than 1000 seconds).
  363  * These values are chosen based on experiments on low speed network. There is no configuration
  364  * for these timeouts.
  365  *
  366  * @section le_avcService_configdb Service Configuration Tree
  367  * @copydoc le_avcService_configdbPage_Hide
  368  *
  369  *
  370  * Copyright (C) Sierra Wireless Inc.
  371  */
  372 /**
  373  * @interface le_avcService_configdbPage_Hide
  374  *
  375  * The configuration database path for the activityTimeout is:
  376  * @verbatim
  377  /
  378      apps/
  379          avcService/
  380                   activityTimeout
  381  @endverbatim
  382  *
  383  *
  384  * After an AirVantage session is started, if there's no activity between the device and the server
  385  * within the timer interval, then LE_AVC_NO_UPDATE state will be returned to the app. However,
  386  * this activity timeout can be overridden by setting an integer value for
  387  * /apps/avcService/activityTimeout. The activity timer is initialized only when the @c avcService
  388  * starts. If a valid entry >0 is found, then it will be used instead of the default value of 20
  389  * seconds. The following steps should be used to set the activityTimeout.
  390  *
  391  *
  392  * @verbatim
  393  config set /apps/avcService/activityTimeout xx int
  394  app restart avcService
  395  @endverbatim
  396  *
  397  * @note
  398  * Everytime a new value is written to activityTimeout, the avcService needs to be
  399  * restarted to read the new value.
  400  *
  401  *
  402  */
  403 /**
  404  * @file le_avc_interface.h
  405  *
  406  * Legato @ref c_le_avc include file.
  407  *
  408  * Copyright (C) Sierra Wireless Inc.
  409  */
  410 
  411 #ifndef LE_AVC_INTERFACE_H_INCLUDE_GUARD
  412 #define LE_AVC_INTERFACE_H_INCLUDE_GUARD
  413 
  414 
  415 #include "legato.h"
  416 
  417 // Interface specific includes
  418 #include "le_limit_interface.h"
  419 
  420 
  421 //--------------------------------------------------------------------------------------------------
  422 /**
  423  * Type for handler called when a server disconnects.
  424  */
  425 //--------------------------------------------------------------------------------------------------
  426 typedef void (*le_avc_DisconnectHandler_t)(void *);
  427 
  428 //--------------------------------------------------------------------------------------------------
  429 /**
  430  *
  431  * Connect the current client thread to the service providing this API. Block until the service is
  432  * available.
  433  *
  434  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  435  * called before any other functions in this API.  Normally, ConnectService is automatically called
  436  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  437  *
  438  * This function is created automatically.
  439  */
  440 //--------------------------------------------------------------------------------------------------
  441 void le_avc_ConnectService
  442 (
  443     void
  444 );
  445 
  446 //--------------------------------------------------------------------------------------------------
  447 /**
  448  *
  449  * Try to connect the current client thread to the service providing this API. Return with an error
  450  * if the service is not available.
  451  *
  452  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  453  * called before any other functions in this API.  Normally, ConnectService is automatically called
  454  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  455  *
  456  * This function is created automatically.
  457  *
  458  * @return
  459  *  - LE_OK if the client connected successfully to the service.
  460  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  461  *    bound.
  462  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  463  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  464  */
  465 //--------------------------------------------------------------------------------------------------
  466 le_result_t le_avc_TryConnectService
  467 (
  468     void
  469 );
  470 
  471 //--------------------------------------------------------------------------------------------------
  472 /**
  473  * Set handler called when server disconnection is detected.
  474  *
  475  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  476  * to continue without exiting, it should call longjmp() from inside the handler.
  477  */
  478 //--------------------------------------------------------------------------------------------------
  479 void le_avc_SetServerDisconnectHandler
  480 (
  481     le_avc_DisconnectHandler_t disconnectHandler,
  482     void *contextPtr
  483 );
  484 
  485 //--------------------------------------------------------------------------------------------------
  486 /**
  487  *
  488  * Disconnect the current client thread from the service providing this API.
  489  *
  490  * Normally, this function doesn't need to be called. After this function is called, there's no
  491  * longer a connection to the service, and the functions in this API can't be used. For details, see
  492  * @ref apiFilesC_client.
  493  *
  494  * This function is created automatically.
  495  */
  496 //--------------------------------------------------------------------------------------------------
  497 void le_avc_DisconnectService
  498 (
  499     void
  500 );
  501 
  502 
  503 //--------------------------------------------------------------------------------------------------
  504 /**
  505  * Maximum APN name length without NULL terminator.
  506  */
  507 //--------------------------------------------------------------------------------------------------
  508 #define LE_AVC_APN_NAME_MAX_LEN 48
  509 
  510 //--------------------------------------------------------------------------------------------------
  511 /**
  512  * Maximum APN name length including NULL terminator.
  513  */
  514 //--------------------------------------------------------------------------------------------------
  515 #define LE_AVC_APN_NAME_MAX_LEN_BYTES 49
  516 
  517 //--------------------------------------------------------------------------------------------------
  518 /**
  519  * Maximum user name length without NULL terminator.
  520  */
  521 //--------------------------------------------------------------------------------------------------
  522 #define LE_AVC_USERNAME_MAX_LEN 28
  523 
  524 //--------------------------------------------------------------------------------------------------
  525 /**
  526  * Maximum user name length including NULL terminator.
  527  */
  528 //--------------------------------------------------------------------------------------------------
  529 #define LE_AVC_USERNAME_MAX_LEN_BYTES 29
  530 
  531 //--------------------------------------------------------------------------------------------------
  532 /**
  533  * Maximum password length without NULL terminator..
  534  */
  535 //--------------------------------------------------------------------------------------------------
  536 #define LE_AVC_PASSWORD_MAX_LEN 28
  537 
  538 //--------------------------------------------------------------------------------------------------
  539 /**
  540  * Maximum password length including NULL terminator.
  541  */
  542 //--------------------------------------------------------------------------------------------------
  543 #define LE_AVC_PASSWORD_MAX_LEN_BYTES 29
  544 
  545 //--------------------------------------------------------------------------------------------------
  546 /**
  547  * Maximum number of retry timers.
  548  */
  549 //--------------------------------------------------------------------------------------------------
  550 #define LE_AVC_NUM_RETRY_TIMERS 8
  551 
  552 //--------------------------------------------------------------------------------------------------
  553 /**
  554  *  Polling timer value range in minutes. 525600 minutes = 1 year.
  555  */
  556 //--------------------------------------------------------------------------------------------------
  557 #define LE_AVC_POLLING_TIMER_MAX_VAL 525600
  558 
  559 //--------------------------------------------------------------------------------------------------
  560 /**
  561  */
  562 //--------------------------------------------------------------------------------------------------
  563 #define LE_AVC_POLLING_TIMER_MIN_VAL 0
  564 
  565 //--------------------------------------------------------------------------------------------------
  566 /**
  567  *  Retry timer value range in minutes. 20160 minutes = 2 weeks.
  568  */
  569 //--------------------------------------------------------------------------------------------------
  570 #define LE_AVC_RETRY_TIMER_MAX_VAL 20160
  571 
  572 //--------------------------------------------------------------------------------------------------
  573 /**
  574  */
  575 //--------------------------------------------------------------------------------------------------
  576 #define LE_AVC_RETRY_TIMER_MIN_VAL 0
  577 
  578 //--------------------------------------------------------------------------------------------------
  579 /**
  580  * Default HTTP status.
  581  */
  582 //--------------------------------------------------------------------------------------------------
  583 #define LE_AVC_HTTP_STATUS_INVALID 65535
  584 
  585 //--------------------------------------------------------------------------------------------------
  586 /**
  587  * Communication info max string size
  588  */
  589 //--------------------------------------------------------------------------------------------------
  590 #define LE_AVC_COMM_INFO_STR_MAX_LEN 256
  591 
  592 //--------------------------------------------------------------------------------------------------
  593 /**
  594  * Communication info codes
  595  */
  596 //--------------------------------------------------------------------------------------------------
  597 #define LE_AVC_COMM_INFO_UDP_NO_ERR 0
  598 
  599 //--------------------------------------------------------------------------------------------------
  600 /**
  601  */
  602 //--------------------------------------------------------------------------------------------------
  603 #define LE_AVC_COMM_INFO_UDP_OPEN_ERR 1
  604 
  605 //--------------------------------------------------------------------------------------------------
  606 /**
  607  */
  608 //--------------------------------------------------------------------------------------------------
  609 #define LE_AVC_COMM_INFO_UDP_CLOSE_ERR 2
  610 
  611 //--------------------------------------------------------------------------------------------------
  612 /**
  613  */
  614 //--------------------------------------------------------------------------------------------------
  615 #define LE_AVC_COMM_INFO_UDP_SEND_ERR 3
  616 
  617 //--------------------------------------------------------------------------------------------------
  618 /**
  619  */
  620 //--------------------------------------------------------------------------------------------------
  621 #define LE_AVC_COMM_INFO_UDP_RECV_ERR 4
  622 
  623 //--------------------------------------------------------------------------------------------------
  624 /**
  625  */
  626 //--------------------------------------------------------------------------------------------------
  627 #define LE_AVC_COMM_INFO_UDP_CONNECT_ERR 5
  628 
  629 //--------------------------------------------------------------------------------------------------
  630 /**
  631  */
  632 //--------------------------------------------------------------------------------------------------
  633 #define LE_AVC_COMM_INFO_BEARER_UP 6
  634 
  635 //--------------------------------------------------------------------------------------------------
  636 /**
  637  */
  638 //--------------------------------------------------------------------------------------------------
  639 #define LE_AVC_COMM_INFO_BEARER_DOWN 7
  640 
  641 //--------------------------------------------------------------------------------------------------
  642 /**
  643  */
  644 //--------------------------------------------------------------------------------------------------
  645 #define LE_AVC_COMM_INFO_PDP_CONTEXT 8
  646 
  647 //--------------------------------------------------------------------------------------------------
  648 /**
  649  */
  650 //--------------------------------------------------------------------------------------------------
  651 #define LE_AVC_COMM_INFO_COAP_201_CREATED 65
  652 
  653 //--------------------------------------------------------------------------------------------------
  654 /**
  655  */
  656 //--------------------------------------------------------------------------------------------------
  657 #define LE_AVC_COMM_INFO_COAP_202_DELETED 66
  658 
  659 //--------------------------------------------------------------------------------------------------
  660 /**
  661  */
  662 //--------------------------------------------------------------------------------------------------
  663 #define LE_AVC_COMM_INFO_COAP_204_CHANGED 68
  664 
  665 //--------------------------------------------------------------------------------------------------
  666 /**
  667  */
  668 //--------------------------------------------------------------------------------------------------
  669 #define LE_AVC_COMM_INFO_COAP_205_CONTENT 69
  670 
  671 //--------------------------------------------------------------------------------------------------
  672 /**
  673  */
  674 //--------------------------------------------------------------------------------------------------
  675 #define LE_AVC_COMM_INFO_COAP_231_CONTINUE 95
  676 
  677 //--------------------------------------------------------------------------------------------------
  678 /**
  679  */
  680 //--------------------------------------------------------------------------------------------------
  681 #define LE_AVC_COMM_INFO_COAP_400_BAD_REQUEST 128
  682 
  683 //--------------------------------------------------------------------------------------------------
  684 /**
  685  */
  686 //--------------------------------------------------------------------------------------------------
  687 #define LE_AVC_COMM_INFO_COAP_401_UNAUTHORIZED 129
  688 
  689 //--------------------------------------------------------------------------------------------------
  690 /**
  691  */
  692 //--------------------------------------------------------------------------------------------------
  693 #define LE_AVC_COMM_INFO_COAP_402_BAD_OPTION 130
  694 
  695 //--------------------------------------------------------------------------------------------------
  696 /**
  697  */
  698 //--------------------------------------------------------------------------------------------------
  699 #define LE_AVC_COMM_INFO_COAP_404_NOT_FOUND 132
  700 
  701 //--------------------------------------------------------------------------------------------------
  702 /**
  703  */
  704 //--------------------------------------------------------------------------------------------------
  705 #define LE_AVC_COMM_INFO_COAP_405_METHOD_NOT_ALLOWED 133
  706 
  707 //--------------------------------------------------------------------------------------------------
  708 /**
  709  */
  710 //--------------------------------------------------------------------------------------------------
  711 #define LE_AVC_COMM_INFO_COAP_406_NOT_ACCEPTABLE 134
  712 
  713 //--------------------------------------------------------------------------------------------------
  714 /**
  715  */
  716 //--------------------------------------------------------------------------------------------------
  717 #define LE_AVC_COMM_INFO_COAP_408_REQ_ENTITY_INCOMPLETE 136
  718 
  719 //--------------------------------------------------------------------------------------------------
  720 /**
  721  */
  722 //--------------------------------------------------------------------------------------------------
  723 #define LE_AVC_COMM_INFO_COAP_412_PRECONDITION_FAILED 140
  724 
  725 //--------------------------------------------------------------------------------------------------
  726 /**
  727  */
  728 //--------------------------------------------------------------------------------------------------
  729 #define LE_AVC_COMM_INFO_COAP_413_ENTITY_TOO_LARGE 141
  730 
  731 //--------------------------------------------------------------------------------------------------
  732 /**
  733  */
  734 //--------------------------------------------------------------------------------------------------
  735 #define LE_AVC_COMM_INFO_COAP_500_INTERNAL_SERVER_ERROR 160
  736 
  737 //--------------------------------------------------------------------------------------------------
  738 /**
  739  */
  740 //--------------------------------------------------------------------------------------------------
  741 #define LE_AVC_COMM_INFO_COAP_501_NOT_IMPLEMENTED 161
  742 
  743 //--------------------------------------------------------------------------------------------------
  744 /**
  745  */
  746 //--------------------------------------------------------------------------------------------------
  747 #define LE_AVC_COMM_INFO_COAP_503_SERVICE_UNAVAILABLE 163
  748 
  749 //--------------------------------------------------------------------------------------------------
  750 /**
  751  * Status of session or update
  752  *
  753  * If an update is pending, it must first be downloaded and then installed.
  754  */
  755 //--------------------------------------------------------------------------------------------------
  756 typedef enum
  757 {
  758     LE_AVC_NO_UPDATE = 0,
  759         ///< No updates pending
  760     LE_AVC_DOWNLOAD_PENDING = 1,
  761         ///< Update pending download
  762     LE_AVC_DOWNLOAD_IN_PROGRESS = 2,
  763         ///< Download in progress
  764     LE_AVC_DOWNLOAD_COMPLETE = 3,
  765         ///< Download has completed
  766     LE_AVC_DOWNLOAD_FAILED = 4,
  767         ///< An error occurred downloading the update
  768     LE_AVC_INSTALL_PENDING = 5,
  769         ///< Install is pending (implies download complete)
  770     LE_AVC_INSTALL_IN_PROGRESS = 6,
  771         ///< Install in progress
  772     LE_AVC_INSTALL_COMPLETE = 7,
  773         ///< Update has been successfully installed
  774     LE_AVC_INSTALL_FAILED = 8,
  775         ///< An error occurred installing the update
  776     LE_AVC_UNINSTALL_PENDING = 9,
  777         ///< Uninstall is pending
  778     LE_AVC_UNINSTALL_IN_PROGRESS = 10,
  779         ///< Uninstall in progress
  780     LE_AVC_UNINSTALL_COMPLETE = 11,
  781         ///< App has been successfully uninstalled
  782     LE_AVC_UNINSTALL_FAILED = 12,
  783         ///< An error occurred uninstalling the update
  784     LE_AVC_SESSION_STARTED = 13,
  785         ///< Session with AirVantage device management server started
  786     LE_AVC_SESSION_BS_STARTED = 14,
  787         ///< Session with bootstrap server started
  788     LE_AVC_SESSION_STOPPED = 15,
  789         ///< Session with AirVantage device management server or bootstrap
  790         ///< server stopped
  791     LE_AVC_SESSION_FAILED = 16,
  792         ///< Session with AirVantage device management server or bootstrap
  793         ///< server failed
  794     LE_AVC_REBOOT_PENDING = 17,
  795         ///< Device reboot is pending
  796     LE_AVC_CONNECTION_PENDING = 18,
  797         ///< Connection to the server is required. This is necessary when
  798         ///< firmware package is installed (after a platform reboot). Also
  799         ///< necessary after software update if device reboots(or session stops)
  800         ///< in the middle of software update.
  801     LE_AVC_AUTH_STARTED = 19,
  802         ///< Authentication with AirVantage device management server or
  803         ///< bootstrap server started
  804     LE_AVC_AUTH_FAILED = 20,
  805         ///< Authentication with AirVantage device management server or
  806         ///< bootstrap server failed
  807     LE_AVC_CERTIFICATION_OK = 21,
  808         ///< Package is certified sent by a trusted server
  809     LE_AVC_CERTIFICATION_KO = 22
  810         ///< Package is not certified sent by a trusted server
  811 }
  812 le_avc_Status_t;
  813 
  814 
  815 //--------------------------------------------------------------------------------------------------
  816 /**
  817  * Operations which require user agreement
  818  */
  819 //--------------------------------------------------------------------------------------------------
  820 typedef enum
  821 {
  822     LE_AVC_USER_AGREEMENT_CONNECTION = 0,
  823         ///< User agreement for connection
  824     LE_AVC_USER_AGREEMENT_DOWNLOAD = 1,
  825         ///< User agreement for download
  826     LE_AVC_USER_AGREEMENT_INSTALL = 2,
  827         ///< User agreement for install
  828     LE_AVC_USER_AGREEMENT_UNINSTALL = 3,
  829         ///< User agreement for uninstall
  830     LE_AVC_USER_AGREEMENT_REBOOT = 4
  831         ///< User agreement for reboot
  832 }
  833 le_avc_UserAgreement_t;
  834 
  835 
  836 //--------------------------------------------------------------------------------------------------
  837 /**
  838  * Request to open or close avms session.
  839  */
  840 //--------------------------------------------------------------------------------------------------
  841 typedef enum
  842 {
  843     LE_AVC_SESSION_ACQUIRE = 0,
  844         ///< Request by user app to open AV session
  845     LE_AVC_SESSION_RELEASE = 1
  846         ///< Request by user app to close AV session
  847 }
  848 le_avc_SessionRequest_t;
  849 
  850 
  851 //--------------------------------------------------------------------------------------------------
  852 /**
  853  * The type of pending update
  854  */
  855 //--------------------------------------------------------------------------------------------------
  856 typedef enum
  857 {
  858     LE_AVC_UNKNOWN_UPDATE = 0,
  859         ///<
  860     LE_AVC_FIRMWARE_UPDATE = 1,
  861         ///<
  862     LE_AVC_FRAMEWORK_UPDATE = 2,
  863         ///<
  864     LE_AVC_APPLICATION_UPDATE = 3
  865         ///<
  866 }
  867 le_avc_UpdateType_t;
  868 
  869 
  870 //--------------------------------------------------------------------------------------------------
  871 /**
  872  * Error code used to provide diagnostic information after a failure (includes both download and
  873  * install failure).
  874  *
  875  * @note
  876  *     Additional information may also be available in the target device's system log.
  877  */
  878 //--------------------------------------------------------------------------------------------------
  879 typedef enum
  880 {
  881     LE_AVC_ERR_NONE = 0,
  882         ///< No error.
  883     LE_AVC_ERR_BAD_PACKAGE = 1,
  884         ///< Encountered a bad package.
  885     LE_AVC_ERR_INTERNAL = 2,
  886         ///< Something failed while doing install/download.
  887     LE_AVC_ERR_SECURITY_FAILURE = 3
  888         ///< Security check failure while installing the package.
  889 }
  890 le_avc_ErrorCode_t;
  891 
  892 
  893 //--------------------------------------------------------------------------------------------------
  894 /**
  895  * Session type indicates whether the device is connected to the bootstrap server or the
  896  * device management server.
  897  */
  898 //--------------------------------------------------------------------------------------------------
  899 typedef enum
  900 {
  901     LE_AVC_BOOTSTRAP_SESSION = 0,
  902         ///< Bootstrap session.
  903     LE_AVC_DM_SESSION = 1,
  904         ///< Device Management session.
  905     LE_AVC_SESSION_INVALID = 2
  906         ///< Session type invalid.
  907 }
  908 le_avc_SessionType_t;
  909 
  910 
  911 //--------------------------------------------------------------------------------------------------
  912 /**
  913  * Status of the device credentials
  914  */
  915 //--------------------------------------------------------------------------------------------------
  916 typedef enum
  917 {
  918     LE_AVC_NO_CREDENTIAL_PROVISIONED = 1,
  919         ///< Neither Bootstrap nor Device Management
  920         ///< credential is provisioned.
  921     LE_AVC_BS_CREDENTIAL_PROVISIONED = 2,
  922         ///< Bootstrap credential is provisioned but Device
  923         ///< Management credential is not provisioned.
  924     LE_AVC_DM_CREDENTIAL_PROVISIONED = 3
  925         ///< Device Management credential is provisioned.
  926 }
  927 le_avc_CredentialStatus_t;
  928 
  929 
  930 //--------------------------------------------------------------------------------------------------
  931 /**
  932  * Reference type used by Add/Remove functions for EVENT 'le_avc_StatusEvent'
  933  */
  934 //--------------------------------------------------------------------------------------------------
  935 typedef struct le_avc_StatusEventHandler* le_avc_StatusEventHandlerRef_t;
  936 
  937 
  938 //--------------------------------------------------------------------------------------------------
  939 /**
  940  * Reference type used by Add/Remove functions for EVENT 'le_avc_SessionRequestEvent'
  941  */
  942 //--------------------------------------------------------------------------------------------------
  943 typedef struct le_avc_SessionRequestEventHandler* le_avc_SessionRequestEventHandlerRef_t;
  944 
  945 
  946 //--------------------------------------------------------------------------------------------------
  947 /**
  948  * Reference type used by Add/Remove functions for EVENT 'le_avc_CommInfo'
  949  */
  950 //--------------------------------------------------------------------------------------------------
  951 typedef struct le_avc_CommInfoHandler* le_avc_CommInfoHandlerRef_t;
  952 
  953 
  954 //--------------------------------------------------------------------------------------------------
  955 /**
  956  * Reference returned by BlockInstall function and used by UnblockInstall function
  957  */
  958 //--------------------------------------------------------------------------------------------------
  959 typedef struct le_avc_BlockRequest* le_avc_BlockRequestRef_t;
  960 
  961 
  962 //--------------------------------------------------------------------------------------------------
  963 /**
  964  * Handler for update availability status
  965  */
  966 //--------------------------------------------------------------------------------------------------
  967 typedef void (*le_avc_StatusHandlerFunc_t)
  968 (
  969     le_avc_Status_t updateStatus,
  970         ///< status of pending update, if available
  971     int32_t totalNumBytes,
  972         ///< Total number of bytes to be downloaded
  973         ///< only valid when updateStatus is one of
  974         ///< DOWNLOAD_PENDING, DOWNLOAD_IN_PROGRESS or DOWNLOAD_COMPLETE.
  975         ///< returns -1 if value is unknown
  976     int32_t progress,
  977         ///< Task completion in percentage
  978         ///< Valid when updateStatus is one of DOWNLOAD_IN_PROGRESS,
  979         ///< INSTALL_IN_PROGRESS or UNINSTALL_IN_PROGRESS.
  980         ///< returns -1 if value is unknown
  981     void* contextPtr
  982         ///<
  983 );
  984 
  985 //--------------------------------------------------------------------------------------------------
  986 /**
  987  * Handler for receiving session open or close request.
  988  */
  989 //--------------------------------------------------------------------------------------------------
  990 typedef void (*le_avc_SessionRequestHandlerFunc_t)
  991 (
  992     le_avc_SessionRequest_t request,
  993         ///< Request to open or close AV session
  994     void* contextPtr
  995         ///<
  996 );
  997 
  998 //--------------------------------------------------------------------------------------------------
  999 /**
 1000  * Handler for receiving communication information.
 1001  */
 1002 //--------------------------------------------------------------------------------------------------
 1003 typedef void (*le_avc_CommInfoHandlerFunc_t)
 1004 (
 1005     uint8_t code,
 1006         ///< Communication information code
 1007     const char* LE_NONNULL str,
 1008         ///< Communication information string
 1009     void* contextPtr
 1010         ///<
 1011 );
 1012 
 1013 //--------------------------------------------------------------------------------------------------
 1014 /**
 1015  * Add handler function for EVENT 'le_avc_StatusEvent'
 1016  *
 1017  * This event provides information on update availability status
 1018  */
 1019 //--------------------------------------------------------------------------------------------------
 1020 le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler
 1021 (
 1022     le_avc_StatusHandlerFunc_t handlerPtr,
 1023         ///< [IN]
 1024     void* contextPtr
 1025         ///< [IN]
 1026 );
 1027 
 1028 //--------------------------------------------------------------------------------------------------
 1029 /**
 1030  * Remove handler function for EVENT 'le_avc_StatusEvent'
 1031  */
 1032 //--------------------------------------------------------------------------------------------------
 1033 void le_avc_RemoveStatusEventHandler
 1034 (
 1035     le_avc_StatusEventHandlerRef_t handlerRef
 1036         ///< [IN]
 1037 );
 1038 
 1039 //--------------------------------------------------------------------------------------------------
 1040 /**
 1041  * Add handler function for EVENT 'le_avc_SessionRequestEvent'
 1042  *
 1043  * This event provides information on session open or close request.
 1044  */
 1045 //--------------------------------------------------------------------------------------------------
 1046 le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler
 1047 (
 1048     le_avc_SessionRequestHandlerFunc_t handlerPtr,
 1049         ///< [IN]
 1050     void* contextPtr
 1051         ///< [IN]
 1052 );
 1053 
 1054 //--------------------------------------------------------------------------------------------------
 1055 /**
 1056  * Remove handler function for EVENT 'le_avc_SessionRequestEvent'
 1057  */
 1058 //--------------------------------------------------------------------------------------------------
 1059 void le_avc_RemoveSessionRequestEventHandler
 1060 (
 1061     le_avc_SessionRequestEventHandlerRef_t handlerRef
 1062         ///< [IN]
 1063 );
 1064 
 1065 //--------------------------------------------------------------------------------------------------
 1066 /**
 1067  * Add handler function for EVENT 'le_avc_CommInfo'
 1068  *
 1069  * This event provides communication errors.
 1070  */
 1071 //--------------------------------------------------------------------------------------------------
 1072 le_avc_CommInfoHandlerRef_t le_avc_AddCommInfoHandler
 1073 (
 1074     le_avc_CommInfoHandlerFunc_t handlerPtr,
 1075         ///< [IN]
 1076     void* contextPtr
 1077         ///< [IN]
 1078 );
 1079 
 1080 //--------------------------------------------------------------------------------------------------
 1081 /**
 1082  * Remove handler function for EVENT 'le_avc_CommInfo'
 1083  */
 1084 //--------------------------------------------------------------------------------------------------
 1085 void le_avc_RemoveCommInfoHandler
 1086 (
 1087     le_avc_CommInfoHandlerRef_t handlerRef
 1088         ///< [IN]
 1089 );
 1090 
 1091 //--------------------------------------------------------------------------------------------------
 1092 /**
 1093  * Start a session with the AirVantage server
 1094  *
 1095  * This will cause a query to be sent to the server, for pending updates.
 1096  *
 1097  * @return
 1098  *      - LE_OK if connection request has been sent.
 1099  *      - LE_FAULT on failure
 1100  *      - LE_DUPLICATE if already connected.
 1101  */
 1102 //--------------------------------------------------------------------------------------------------
 1103 le_result_t le_avc_StartSession
 1104 (
 1105     void
 1106 );
 1107 
 1108 //--------------------------------------------------------------------------------------------------
 1109 /**
 1110  * Stop a session with the AirVantage server
 1111  *
 1112  * If a download is in progress, then this suspends the download.
 1113  *
 1114  * @return
 1115  *      - LE_OK on success
 1116  *      - LE_FAULT on failure
 1117  *      - LE_DUPLICATE if already disconnected
 1118  */
 1119 //--------------------------------------------------------------------------------------------------
 1120 le_result_t le_avc_StopSession
 1121 (
 1122     void
 1123 );
 1124 
 1125 //--------------------------------------------------------------------------------------------------
 1126 /**
 1127  * Send a specific message to the server to be sure that the route between the device and the server
 1128  * is available.
 1129  * This API needs to be called when any package download is over (successfully or not) and before
 1130  * sending any notification on asset data to the server.
 1131  *
 1132  * @return
 1133  *      - LE_OK when the treatment is launched
 1134  *      - LE_FAULT on failure
 1135  *      - LE_UNSUPPORTED when the API is not supported
 1136  *
 1137  */
 1138 //--------------------------------------------------------------------------------------------------
 1139 le_result_t le_avc_CheckRoute
 1140 (
 1141     void
 1142 );
 1143 
 1144 //--------------------------------------------------------------------------------------------------
 1145 /**
 1146  * Defer the currently pending connection, for the given number of minutes
 1147  *
 1148  * @return
 1149  *      - LE_OK on success
 1150  *      - LE_FAULT on failure
 1151  */
 1152 //--------------------------------------------------------------------------------------------------
 1153 le_result_t le_avc_DeferConnect
 1154 (
 1155     uint32_t deferMinutes
 1156         ///< [IN]
 1157 );
 1158 
 1159 //--------------------------------------------------------------------------------------------------
 1160 /**
 1161  * Accept the currently pending download
 1162  *
 1163  * @return
 1164  *      - LE_OK on success
 1165  *      - LE_FAULT on failure
 1166  */
 1167 //--------------------------------------------------------------------------------------------------
 1168 le_result_t le_avc_AcceptDownload
 1169 (
 1170     void
 1171 );
 1172 
 1173 //--------------------------------------------------------------------------------------------------
 1174 /**
 1175  * Defer the currently pending download, for the given number of minutes
 1176  *
 1177  * @return
 1178  *      - LE_OK on success
 1179  *      - LE_FAULT on failure
 1180  */
 1181 //--------------------------------------------------------------------------------------------------
 1182 le_result_t le_avc_DeferDownload
 1183 (
 1184     uint32_t deferMinutes
 1185         ///< [IN]
 1186 );
 1187 
 1188 //--------------------------------------------------------------------------------------------------
 1189 /**
 1190  * Accept the currently pending install
 1191  *
 1192  * @return
 1193  *      - LE_OK on success
 1194  *      - LE_FAULT on failure
 1195  */
 1196 //--------------------------------------------------------------------------------------------------
 1197 le_result_t le_avc_AcceptInstall
 1198 (
 1199     void
 1200 );
 1201 
 1202 //--------------------------------------------------------------------------------------------------
 1203 /**
 1204  * Defer the currently pending install
 1205  *
 1206  * @return
 1207  *      - LE_OK on success
 1208  *      - LE_FAULT on failure
 1209  */
 1210 //--------------------------------------------------------------------------------------------------
 1211 le_result_t le_avc_DeferInstall
 1212 (
 1213     uint32_t deferMinutes
 1214         ///< [IN]
 1215 );
 1216 
 1217 //--------------------------------------------------------------------------------------------------
 1218 /**
 1219  * Accept the currently pending uninstall
 1220  *
 1221  * @return
 1222  *      - LE_OK on success
 1223  *      - LE_FAULT on failure
 1224  */
 1225 //--------------------------------------------------------------------------------------------------
 1226 le_result_t le_avc_AcceptUninstall
 1227 (
 1228     void
 1229 );
 1230 
 1231 //--------------------------------------------------------------------------------------------------
 1232 /**
 1233  * Defer the currently pending uninstall
 1234  *
 1235  * @return
 1236  *      - LE_OK on success
 1237  *      - LE_FAULT on failure
 1238  */
 1239 //--------------------------------------------------------------------------------------------------
 1240 le_result_t le_avc_DeferUninstall
 1241 (
 1242     uint32_t deferMinutes
 1243         ///< [IN]
 1244 );
 1245 
 1246 //--------------------------------------------------------------------------------------------------
 1247 /**
 1248  * Accept the currently pending reboot
 1249  *
 1250  * @return
 1251  *      - LE_OK on success
 1252  *      - LE_FAULT on failure
 1253  */
 1254 //--------------------------------------------------------------------------------------------------
 1255 le_result_t le_avc_AcceptReboot
 1256 (
 1257     void
 1258 );
 1259 
 1260 //--------------------------------------------------------------------------------------------------
 1261 /**
 1262  * Defer the currently pending reboot
 1263  *
 1264  * @return
 1265  *      - LE_OK on success
 1266  *      - LE_FAULT on failure
 1267  */
 1268 //--------------------------------------------------------------------------------------------------
 1269 le_result_t le_avc_DeferReboot
 1270 (
 1271     uint32_t deferMinutes
 1272         ///< [IN]
 1273 );
 1274 
 1275 //--------------------------------------------------------------------------------------------------
 1276 /**
 1277  * Get the update type of the currently pending update
 1278  *
 1279  * @return
 1280  *      - LE_OK on success
 1281  *      - LE_FAULT if not available
 1282  */
 1283 //--------------------------------------------------------------------------------------------------
 1284 le_result_t le_avc_GetUpdateType
 1285 (
 1286     le_avc_UpdateType_t* updateTypePtr
 1287         ///< [OUT]
 1288 );
 1289 
 1290 //--------------------------------------------------------------------------------------------------
 1291 /**
 1292  * Get the name for the currently pending app update
 1293  *
 1294  * @return
 1295  *      - LE_OK on success
 1296  *      - LE_FAULT if not available, or isn't APPL_UPDATE type
 1297  */
 1298 //--------------------------------------------------------------------------------------------------
 1299 le_result_t le_avc_GetAppUpdateName
 1300 (
 1301     char* updateName,
 1302         ///< [OUT]
 1303     size_t updateNameSize
 1304         ///< [IN]
 1305 );
 1306 
 1307 //--------------------------------------------------------------------------------------------------
 1308 /**
 1309  * Prevent any pending updates from being installed.
 1310  *
 1311  * @return
 1312  *      - Reference for block update request (to be used later for unblocking updates)
 1313  *      - NULL if the operation was not successful
 1314  */
 1315 //--------------------------------------------------------------------------------------------------
 1316 le_avc_BlockRequestRef_t le_avc_BlockInstall
 1317 (
 1318     void
 1319 );
 1320 
 1321 //--------------------------------------------------------------------------------------------------
 1322 /**
 1323  * Allow any pending updates to be installed
 1324  */
 1325 //--------------------------------------------------------------------------------------------------
 1326 void le_avc_UnblockInstall
 1327 (
 1328     le_avc_BlockRequestRef_t blockRef
 1329         ///< [IN] block request ref returned by le_avc_BlockInstall
 1330 );
 1331 
 1332 //--------------------------------------------------------------------------------------------------
 1333 /**
 1334  * Function to get error code when update fails.
 1335  *
 1336  * @return
 1337  *      - Error code of encountered error.
 1338  *      - ERR_NONE if update is in any other state.
 1339  */
 1340 //--------------------------------------------------------------------------------------------------
 1341 le_avc_ErrorCode_t le_avc_GetErrorCode
 1342 (
 1343     void
 1344 );
 1345 
 1346 //--------------------------------------------------------------------------------------------------
 1347 /**
 1348  * Function to read the current session type, or the last session type if there is no
 1349  * active session.
 1350  *
 1351  * @return
 1352  *      - SessionType
 1353  */
 1354 //--------------------------------------------------------------------------------------------------
 1355 le_avc_SessionType_t le_avc_GetSessionType
 1356 (
 1357     void
 1358 );
 1359 
 1360 //--------------------------------------------------------------------------------------------------
 1361 /**
 1362  * Function to read the http status of the last download.
 1363  *
 1364  * @return
 1365  *      - HttpStatus as defined in RFC 7231, Section 6.
 1366  */
 1367 //--------------------------------------------------------------------------------------------------
 1368 uint16_t le_avc_GetHttpStatus
 1369 (
 1370     void
 1371 );
 1372 
 1373 //--------------------------------------------------------------------------------------------------
 1374 /**
 1375  * Function to read the polling timer.
 1376  *
 1377  * @return
 1378  *      - LE_OK on success
 1379  *      - LE_FAULT if not available
 1380  *      - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
 1381  */
 1382 //--------------------------------------------------------------------------------------------------
 1383 le_result_t le_avc_GetPollingTimer
 1384 (
 1385     uint32_t* pollingTimerPtr
 1386         ///< [OUT] Polling timer
 1387 );
 1388 
 1389 //--------------------------------------------------------------------------------------------------
 1390 /**
 1391  * Function to read the retry timers.
 1392  *
 1393  * @return
 1394  *      - LE_OK on success.
 1395  *      - LE_FAULT if not able to read the timers.
 1396  *      - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
 1397  */
 1398 //--------------------------------------------------------------------------------------------------
 1399 le_result_t le_avc_GetRetryTimers
 1400 (
 1401     uint16_t* timerValuePtr,
 1402         ///< [OUT] Array of the retry timers.
 1403     size_t* timerValueSizePtr
 1404         ///< [INOUT]
 1405 );
 1406 
 1407 //--------------------------------------------------------------------------------------------------
 1408 /**
 1409  * Function to read APN configuration.
 1410  *
 1411  * @return
 1412  *      - LE_OK on success.
 1413  *      - LE_FAULT if there is any error while reading.
 1414  *      - LE_OVERFLOW if the buffer provided is too small.
 1415  */
 1416 //--------------------------------------------------------------------------------------------------
 1417 le_result_t le_avc_GetApnConfig
 1418 (
 1419     char* apnName,
 1420         ///< [OUT]
 1421     size_t apnNameSize,
 1422         ///< [IN]
 1423     char* userName,
 1424         ///< [OUT]
 1425     size_t userNameSize,
 1426         ///< [IN]
 1427     char* userPwd,
 1428         ///< [OUT]
 1429     size_t userPwdSize
 1430         ///< [IN]
 1431 );
 1432 
 1433 //--------------------------------------------------------------------------------------------------
 1434 /**
 1435  * Function to write APN configuration.
 1436  *
 1437  * @return
 1438  *      - LE_OK on success.
 1439  *      - LE_OVERFLOW if one of the input strings is too long.
 1440  */
 1441 //--------------------------------------------------------------------------------------------------
 1442 le_result_t le_avc_SetApnConfig
 1443 (
 1444     const char* LE_NONNULL apnName,
 1445         ///< [IN]
 1446     const char* LE_NONNULL userName,
 1447         ///< [IN]
 1448     const char* LE_NONNULL userPwd
 1449         ///< [IN]
 1450 );
 1451 
 1452 //--------------------------------------------------------------------------------------------------
 1453 /**
 1454  * Function to set the polling timer.
 1455  *
 1456  * @return
 1457  *      - LE_OK on success.
 1458  *      - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
 1459  */
 1460 //--------------------------------------------------------------------------------------------------
 1461 le_result_t le_avc_SetPollingTimer
 1462 (
 1463     uint32_t pollingTimer
 1464         ///< [IN] Polling timer
 1465 );
 1466 
 1467 //--------------------------------------------------------------------------------------------------
 1468 /**
 1469  * Function to set the retry timers.
 1470  *
 1471  * @return
 1472  *      - LE_OK on success.
 1473  *      - LE_FAULT if not able to set the timers.
 1474  *      - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
 1475  */
 1476 //--------------------------------------------------------------------------------------------------
 1477 le_result_t le_avc_SetRetryTimers
 1478 (
 1479     const uint16_t* timerValuePtr,
 1480         ///< [IN] Array of 8 retry timers.
 1481     size_t timerValueSize
 1482         ///< [IN]
 1483 );
 1484 
 1485 //--------------------------------------------------------------------------------------------------
 1486 /**
 1487  * Function to retrieve status of the credentials provisioned on the device.
 1488  *
 1489  * @return
 1490  *     LE_AVC_NO_CREDENTIAL_PROVISIONED
 1491  *          - If neither Bootstrap nor Device Management credential is provisioned.
 1492  *     LE_AVC_BS_CREDENTIAL_PROVISIONED
 1493  *          - If Bootstrap credential is provisioned but Device Management credential is
 1494  *              not provisioned.
 1495  *     LE_AVC_DM_CREDENTIAL_PROVISIONED
 1496  *          - If Device management key is provisioned.
 1497  */
 1498 //--------------------------------------------------------------------------------------------------
 1499 le_avc_CredentialStatus_t le_avc_GetCredentialStatus
 1500 (
 1501     void
 1502 );
 1503 
 1504 //--------------------------------------------------------------------------------------------------
 1505 /**
 1506  * Function to set user agreements for download, install, reboot, connection and uninstall.
 1507  *
 1508  * @return
 1509  *      - LE_OK on success.
 1510  *      - LE_FAULT if failed to configure user agreement.
 1511  */
 1512 //--------------------------------------------------------------------------------------------------
 1513 le_result_t le_avc_SetUserAgreement
 1514 (
 1515     le_avc_UserAgreement_t updateStatus,
 1516         ///< [IN] Operation for which user agreements has to be set.
 1517     bool enable
 1518         ///< [IN] true = enable, false = disable.
 1519 );
 1520 
 1521 //--------------------------------------------------------------------------------------------------
 1522 /**
 1523  * Function to get user agreements for download, install, reboot, connection and uninstall.
 1524  *
 1525  * @return
 1526  *      - LE_OK on success.
 1527  *      - LE_FAULT if failed to read user agreement state.
 1528  */
 1529 //--------------------------------------------------------------------------------------------------
 1530 le_result_t le_avc_GetUserAgreement
 1531 (
 1532     le_avc_UserAgreement_t updateStatus,
 1533         ///< [IN] Operation for which user agreements has to be read.
 1534     bool* enablePtr
 1535         ///< [OUT] true = enable, false = disable.
 1536 );
 1537 
 1538 #endif // LE_AVC_INTERFACE_H_INCLUDE_GUARD
le_avc_RemoveSessionRequestEventHandler
void le_avc_RemoveSessionRequestEventHandler(le_avc_SessionRequestEventHandlerRef_t handlerRef)
le_avc_GetPollingTimer
le_result_t le_avc_GetPollingTimer(uint32_t *pollingTimerPtr)
LE_AVC_UNINSTALL_IN_PROGRESS
Uninstall in progress. 
Definition: le_avc_interface.h:778
LE_AVC_UNINSTALL_PENDING
Uninstall is pending. 
Definition: le_avc_interface.h:776
LE_AVC_SESSION_RELEASE
Request by user app to close AV session. 
Definition: le_avc_interface.h:845
LE_AVC_USER_AGREEMENT_REBOOT
User agreement for reboot. 
Definition: le_avc_interface.h:830
LE_AVC_USER_AGREEMENT_CONNECTION
User agreement for connection. 
Definition: le_avc_interface.h:822
LE_AVC_INSTALL_FAILED
An error occurred installing the update. 
Definition: le_avc_interface.h:774
le_avc_DeferReboot
le_result_t le_avc_DeferReboot(uint32_t deferMinutes)
le_avc_SetRetryTimers
le_result_t le_avc_SetRetryTimers(const uint16_t *timerValuePtr, size_t timerValueSize)
le_avc_AddSessionRequestEventHandler
le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler(le_avc_SessionRequestHandlerFunc_t handlerPtr, void *contextPtr)
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_DeferConnect
le_result_t le_avc_DeferConnect(uint32_t deferMinutes)
le_result_t
le_result_t
Definition: le_basics.h:35
le_avc_AddCommInfoHandler
le_avc_CommInfoHandlerRef_t le_avc_AddCommInfoHandler(le_avc_CommInfoHandlerFunc_t handlerPtr, void *contextPtr)
LE_AVC_CERTIFICATION_OK
Package is certified sent by a trusted server. 
Definition: le_avc_interface.h:807
le_avc_SessionRequestHandlerFunc_t
void(* le_avc_SessionRequestHandlerFunc_t)(le_avc_SessionRequest_t request, void *contextPtr)
Definition: le_avc_interface.h:991
le_avc_AcceptReboot
le_result_t le_avc_AcceptReboot(void)
LE_AVC_UNINSTALL_FAILED
An error occurred uninstalling the update. 
Definition: le_avc_interface.h:782
le_avc_CommInfoHandlerFunc_t
void(* le_avc_CommInfoHandlerFunc_t)(uint8_t code, const char *LE_NONNULL str, void *contextPtr)
Definition: le_avc_interface.h:1004
LE_AVC_INSTALL_IN_PROGRESS
Install in progress. 
Definition: le_avc_interface.h:770
le_avc_UnblockInstall
void le_avc_UnblockInstall(le_avc_BlockRequestRef_t blockRef)
LE_AVC_CERTIFICATION_KO
Package is not certified sent by a trusted server. 
Definition: le_avc_interface.h:809
le_avc_SetServerDisconnectHandler
void le_avc_SetServerDisconnectHandler(le_avc_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_avc_AddStatusEventHandler
le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler(le_avc_StatusHandlerFunc_t handlerPtr, void *contextPtr)
le_avc_SessionRequestEventHandlerRef_t
struct le_avc_SessionRequestEventHandler * le_avc_SessionRequestEventHandlerRef_t
Definition: le_avc_interface.h:943
le_avc_RemoveCommInfoHandler
void le_avc_RemoveCommInfoHandler(le_avc_CommInfoHandlerRef_t handlerRef)
le_avc_SessionRequest_t
le_avc_SessionRequest_t
Definition: le_avc_interface.h:841
LE_AVC_DOWNLOAD_FAILED
An error occurred downloading the update. 
Definition: le_avc_interface.h:766
le_avc_UserAgreement_t
le_avc_UserAgreement_t
Definition: le_avc_interface.h:820
le_avc_DeferUninstall
le_result_t le_avc_DeferUninstall(uint32_t deferMinutes)
LE_AVC_INSTALL_PENDING
Install is pending (implies download complete) 
Definition: le_avc_interface.h:768
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_DisconnectHandler_t
void(* le_avc_DisconnectHandler_t)(void *)
Definition: le_avc_interface.h:426
LE_AVC_SESSION_STOPPED
Definition: le_avc_interface.h:788
LE_AVC_SESSION_STARTED
Session with AirVantage device management server started. 
Definition: le_avc_interface.h:784
le_avc_SessionType_t
le_avc_SessionType_t
Definition: le_avc_interface.h:899
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_interface.h:968
LE_AVC_DOWNLOAD_IN_PROGRESS
Download in progress. 
Definition: le_avc_interface.h:762
LE_AVC_NO_CREDENTIAL_PROVISIONED
Definition: le_avc_interface.h:918
LE_AVC_REBOOT_PENDING
Device reboot is pending. 
Definition: le_avc_interface.h:794
LE_AVC_SESSION_INVALID
Session type invalid. 
Definition: le_avc_interface.h:905
le_avc_StartSession
le_result_t le_avc_StartSession(void)
le_avc_StopSession
le_result_t le_avc_StopSession(void)
le_avc_RemoveStatusEventHandler
void le_avc_RemoveStatusEventHandler(le_avc_StatusEventHandlerRef_t handlerRef)
LE_AVC_SESSION_FAILED
Definition: le_avc_interface.h:791
LE_AVC_AUTH_STARTED
Definition: le_avc_interface.h:801
le_avc_GetUserAgreement
le_result_t le_avc_GetUserAgreement(le_avc_UserAgreement_t updateStatus, bool *enablePtr)
LE_AVC_DOWNLOAD_PENDING
Update pending download. 
Definition: le_avc_interface.h:760
LE_AVC_USER_AGREEMENT_UNINSTALL
User agreement for uninstall. 
Definition: le_avc_interface.h:828
le_avc_AcceptDownload
le_result_t le_avc_AcceptDownload(void)
le_avc_TryConnectService
le_result_t le_avc_TryConnectService(void)
le_avc_CheckRoute
le_result_t le_avc_CheckRoute(void)
le_avc_DeferInstall
le_result_t le_avc_DeferInstall(uint32_t deferMinutes)
LE_AVC_INSTALL_COMPLETE
Update has been successfully installed. 
Definition: le_avc_interface.h:772
LE_AVC_USER_AGREEMENT_INSTALL
User agreement for install. 
Definition: le_avc_interface.h:826
le_limit_interface.h
le_avc_AcceptInstall
le_result_t le_avc_AcceptInstall(void)
LE_AVC_ERR_INTERNAL
Something failed while doing install/download. 
Definition: le_avc_interface.h:885
LE_AVC_USER_AGREEMENT_DOWNLOAD
User agreement for download. 
Definition: le_avc_interface.h:824
LE_AVC_BOOTSTRAP_SESSION
Bootstrap session. 
Definition: le_avc_interface.h:901
le_avc_BlockRequestRef_t
struct le_avc_BlockRequest * le_avc_BlockRequestRef_t
Definition: le_avc_interface.h:959
le_avc_BlockInstall
le_avc_BlockRequestRef_t le_avc_BlockInstall(void)
le_avc_DisconnectService
void le_avc_DisconnectService(void)
le_avc_GetSessionType
le_avc_SessionType_t le_avc_GetSessionType(void)
LE_AVC_SESSION_BS_STARTED
Session with bootstrap server started. 
Definition: le_avc_interface.h:786
LE_AVC_DM_SESSION
Device Management session. 
Definition: le_avc_interface.h:903
LE_AVC_ERR_NONE
No error. 
Definition: le_avc_interface.h:881
legato.h
le_avc_SetUserAgreement
le_result_t le_avc_SetUserAgreement(le_avc_UserAgreement_t updateStatus, bool enable)
LE_AVC_BS_CREDENTIAL_PROVISIONED
Definition: le_avc_interface.h:921
LE_AVC_CONNECTION_PENDING
Definition: le_avc_interface.h:796
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_UpdateType_t
le_avc_UpdateType_t
Definition: le_avc_interface.h:856
le_avc_GetCredentialStatus
le_avc_CredentialStatus_t le_avc_GetCredentialStatus(void)
le_avc_DeferDownload
le_result_t le_avc_DeferDownload(uint32_t deferMinutes)
le_avc_SetPollingTimer
le_result_t le_avc_SetPollingTimer(uint32_t pollingTimer)
LE_AVC_ERR_SECURITY_FAILURE
Security check failure while installing the package. 
Definition: le_avc_interface.h:887
LE_AVC_SESSION_ACQUIRE
Request by user app to open AV session. 
Definition: le_avc_interface.h:843
le_avc_GetAppUpdateName
le_result_t le_avc_GetAppUpdateName(char *updateName, size_t updateNameSize)
le_avc_ErrorCode_t
le_avc_ErrorCode_t
Definition: le_avc_interface.h:879
LE_AVC_DOWNLOAD_COMPLETE
Download has completed. 
Definition: le_avc_interface.h:764
le_avc_GetRetryTimers
le_result_t le_avc_GetRetryTimers(uint16_t *timerValuePtr, size_t *timerValueSizePtr)
LE_AVC_NO_UPDATE
No updates pending. 
Definition: le_avc_interface.h:758
le_avc_CredentialStatus_t
le_avc_CredentialStatus_t
Definition: le_avc_interface.h:916
le_avc_CommInfoHandlerRef_t
struct le_avc_CommInfoHandler * le_avc_CommInfoHandlerRef_t
Definition: le_avc_interface.h:951
le_avc_GetHttpStatus
uint16_t le_avc_GetHttpStatus(void)
le_avc_StatusEventHandlerRef_t
struct le_avc_StatusEventHandler * le_avc_StatusEventHandlerRef_t
Definition: le_avc_interface.h:935
LE_AVC_ERR_BAD_PACKAGE
Encountered a bad package. 
Definition: le_avc_interface.h:883
le_avc_Status_t
le_avc_Status_t
Definition: le_avc_interface.h:756
LE_AVC_UNINSTALL_COMPLETE
App has been successfully uninstalled. 
Definition: le_avc_interface.h:780
LE_AVC_DM_CREDENTIAL_PROVISIONED
Device Management credential is provisioned. 
Definition: le_avc_interface.h:924
LE_AVC_AUTH_FAILED
Definition: le_avc_interface.h:804
le_avc_GetErrorCode
le_avc_ErrorCode_t le_avc_GetErrorCode(void)
le_avc_ConnectService
void le_avc_ConnectService(void)