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