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
   14  *
   15  * @ref le_avc_interface.h "Type/Function Reference" <br>
   16  * @ref legatoServicesAirVantage "Air Vantage Platform Service"
   17  *
   18  * <HR>
   19  *
   20  * The AirVantage connector service provides an API to communicate with the AirVantage server.
   21  *
   22  * @section c_le_avc_update Firmware/Application Update
   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  *    <br>
   28  *  - Allow an app to block an update from being installed. An app may need this if it's
   29  *    performing a critical operation that can't be interrupted (e.g., eCall). This is necessary
   30  *    as installing an update will cause the app to restart (either the app itself needs to restart
   31  *    or a firmware change causes the modem to reset).
   32  *
   33  * @subsection c_le_avc_update_control Update Control
   34  *
   35  * Any app can start a session with an AirVantage server to determine if there
   36  * is a pending update. This is done with le_avc_StartSession(). The current session can be
   37  * stopped using le_avc_StopSession(). This cancels any query for pending update, or suspends a
   38  * download in progress; however, it <b>won't stop</b> an install in progress.
   39  *
   40  * The status of a pending update is sent to all apps registered for receiving a notification.
   41  * An app can use le_avc_AddStatusEventHandler() to register a handler function to
   42  * receive this notification. The notification will be received after a session is started using
   43  * le_avc_StartSession(). Sometimes, avcService may decide to start a session with the AirVantage
   44  * server; for instance if a call to le_avc_AcceptDownload() when the session is stopped, avcService
   45  * will open a session to proceed with the download. In this case, a session started
   46  * notification could also be received, even if le_avc_StartSession() is not called explicitly.
   47  *
   48  * There can only be one pending update.  To query the type of update, use le_avc_GetUpdateType().
   49  * If it's an app update, then le_avc_GetAppUpdateName() can be used to get the name of
   50  * the app.
   51  *
   52  * If a download is pending, then le_avc_AcceptDownload() can be used to allow the update to be
   53  * downloaded. If this API is called while no AirVantage session is active, calling this API will
   54  * initiate an AirVantage session. To defer the decision, le_avc_DeferDownload() can be used
   55  * to defer the download for the specified number of minutes. After the defer time has elapsed,
   56  * the pending download notification will be re-sent again to all registered apps.
   57  *
   58  * Once an update has been downloaded, a new notification will be received to indicate that an
   59  * install is pending. Apps can then use le_avc_AcceptInstall() to allow the install to proceed.
   60  * Note that even if an app calls le_avc_AcceptInstall(), the install may still be blocked by another
   61  * app using the @ref c_le_avc_update_app functions. To defer the decision, an app can use
   62  * le_avc_DeferInstall() to defer the install for the specified number of minutes. After the defer
   63  * time has elapsed, the pending install notification will be re-sent to allow apps to make a new
   64  * decision, or again defer.
   65  *
   66  * If an uninstall is pending, then le_avc_AcceptUninstall() can be used to allow the uninstall to
   67  * proceed. To defer the decision, le_avc_DeferUninstall() can be used to defer the uninstall for
   68  * the specified number of minutes. In case of an upgrade, the existing application will not be
   69  * uninstalled after le_avc_AcceptUninstall() is called. le_avc_AcceptUninstall() is only used to
   70  * signal the server to start downloading the new application. To proceed with an upgrade process,
   71  * accept the uninstall of the existing version followed by accepting the download and install of
   72  * the new version.
   73  *
   74  * Accepting an app install or uninstall will not initiate an AirVantage session if no session
   75  * is active.  An app should start an AirVantage session before accepting an app install/uninstall,
   76  * to ensure the process is completed, and the server is updated.
   77  *
   78  * If no app has registered for notifications using le_avc_AddStatusEventHandler(),
   79  * then any pending downloads and installs will happen automatically, subject to any restrictions
   80  * imposed by app using the @ref c_le_avc_update_app functions.
   81  *
   82  * There is no restriction on the number of apps registering for notifications.
   83  *
   84  * In case of any error incurred during app download/install, an error code will be set which can be
   85  * retrieved by calling le_avc_GetErrorCode().
   86  *
   87  * @subsection c_le_avc_update_app Application Blocking
   88  *
   89  * When an app is about to perform a critical operation, it can block the installation of
   90  * an update with le_avc_BlockInstall(), and after it's finished with the critical operation, it
   91  * can unblock the install with le_avc_UnblockInstall().
   92  *
   93  * What constitutes a critical operation depends on the app.  An eCall app might
   94  * block installs for the duration that it runs.  A data collection app that wakes up
   95  * once an hour might block installs while it collects and stores and/or transmits a new data
   96  * sample, and then unblock installs just before it goes to sleep again.
   97  *
   98  * If an install can't be applied because it's blocked, another attempt to apply the install
   99  * will be made at a later time.
  100  *
  101  * An app can add a session control handler using le_avc_AddSessionRequestEventHandler(). Requests
  102  * by user apps to open or close session will be forwarded to the session control handler. If no app
  103  * has registered a session request handler, avc session can be opened or closed anytime by
  104  * user apps.
  105  *
  106  * @section c_le_avc_GetPollingTimer Polling Timer
  107  *
  108  * The embedded module will periodically initiate a connection to the Device Services server
  109  * according to the polling timer. The device initates the connection periodically, so that it can
  110  * poll the server if there are any pending jobs. Writing 0 to the polling timer disables polling
  111  * mode. Polling timer values range from 0 to 525600 minutes. The polling timer value is persistent.
  112  * le_avc_GetPollingTimer() reads the polling timer and le_avc_SetPollingTimer() writes the polling
  113  * timer.
  114  *
  115  * @section c_le_avc_GetRetryTimers Retry Timers
  116  * @warning This API should not be used for new applications and will be removed in the future
  117  *
  118  * If an error occurs during a connection to the Device Services server (WWAN DATA establishment
  119  * failed, http error code received), the embedded module will initiate a new connection according
  120  * to the values defined in the retry timers. The timers are tried in sequence until a connection is
  121  * established, or all enabled retry timers are exhausted. After all the enabled timers are
  122  * exhausted, a connection will be initiated only on a command from user (le_avc_startSession() )
  123  * or at the expiry of the polling timer. The retry timer values are persistent. Writing 0
  124  * to one of the retry timers will disable it. Retry timer values range from 0 to 20160 minutes.
  125  * The api le_avc_GetRetryTimers() reads the polling timers in an array and the api
  126  * le_avc_SetRetryTimers() writes the polling timers. When writing to the retry timers, values of
  127  * all the 8 timers have to be defined.
  128  *
  129  * @section c_le_avc_reboot Device reboot
  130  * The AirVantage server can request to reboot the device: in this case a notification is sent to
  131  * registered apps, which can either accept the reboot with le_avc_AcceptReboot() or defer it for
  132  * the specified number of minutes with le_avc_DeferReboot(). After the defer time has elapsed, the
  133  * pending reboot notification will be re-sent, to allow the registered app to make a new decision
  134  * or defer again.
  135  *
  136  * If no app has registered for notifications using le_avc_AddStatusEventHandler(), then
  137  * any pending reboot will happen automatically.
  138  *
  139  * @section c_le_avc_connection Connection required
  140  * The AirVantage agent can request a connection to the AirVantage server, especially when a
  141  * firmware package was installed (after a platform reboot). In this case a notification is sent to
  142  * the control app, which can start the connection with le_avc_StartSession().
  143  *
  144  * @section le_avcService_configdb Service Configuration Tree
  145  * @copydoc le_avcService_configdbPage_Hide
  146  *
  147  * <HR>
  148  *
  149  * Copyright (C) Sierra Wireless Inc.
  150  */
  151 /**
  152  * @interface le_avcService_configdbPage_Hide
  153  *
  154  * The configuration database path for the modemActivityTimeout is:
  155  * @verbatim
  156    /
  157        apps/
  158            avcService/
  159                     modemActivityTimeout
  160    @endverbatim
  161  *
  162  *
  163  * After an AirVantage session is started, if there's no activity from the modem within the timer
  164  * interval, then LE_AVC_NO_UPDATE state will be returned to the app. However, this modem activity
  165  * timeout can be overridden by setting an integer value at /apps/avcService/modemActivityTimeout.
  166  * The modem activity timer is initialized only when the avcService starts. If a valid entry >0 is
  167  * found, then it will be used instead of the default value of 20 seconds. The following steps
  168  * should be used to set the modemActivtyTimeout.
  169  *
  170  *
  171  * @verbatim
  172    config set /apps/avcService/modemActivityTimeout xx
  173    app restart avcService
  174    @endverbatim
  175  *
  176  * @note
  177  * Everytime a new value is written to modemActivityTimeout, the avcService needs to be
  178  * restarted to read the new value.
  179  *
  180  *
  181  */
  182 /**
  183  * @file le_avc_interface.h
  184  *
  185  * Legato @ref c_le_avc include file.
  186  *
  187  * Copyright (C) Sierra Wireless Inc.
  188  */
  189 
  190 #ifndef LE_AVC_INTERFACE_H_INCLUDE_GUARD
  191 #define LE_AVC_INTERFACE_H_INCLUDE_GUARD
  192 
  193 
  194 #include "legato.h"
  195 
  196 // Interface specific includes
  197 #include "le_limit_interface.h"
  198 
  199 
  200 //--------------------------------------------------------------------------------------------------
  201 /**
  202  * Type for handler called when a server disconnects.
  203  */
  204 //--------------------------------------------------------------------------------------------------
  205 typedef void (*le_avc_DisconnectHandler_t)(void *);
  206 
  207 //--------------------------------------------------------------------------------------------------
  208 /**
  209  *
  210  * Connect the current client thread to the service providing this API. Block until the service is
  211  * available.
  212  *
  213  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  214  * called before any other functions in this API.  Normally, ConnectService is automatically called
  215  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  216  *
  217  * This function is created automatically.
  218  */
  219 //--------------------------------------------------------------------------------------------------
  220 void le_avc_ConnectService
  221 (
  222     void
  223 );
  224 
  225 //--------------------------------------------------------------------------------------------------
  226 /**
  227  *
  228  * Try to connect the current client thread to the service providing this API. Return with an error
  229  * if the service is not available.
  230  *
  231  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  232  * called before any other functions in this API.  Normally, ConnectService is automatically called
  233  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  234  *
  235  * This function is created automatically.
  236  *
  237  * @return
  238  *  - LE_OK if the client connected successfully to the service.
  239  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  240  *    bound.
  241  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  242  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  243  */
  244 //--------------------------------------------------------------------------------------------------
  245 le_result_t le_avc_TryConnectService
  246 (
  247     void
  248 );
  249 
  250 //--------------------------------------------------------------------------------------------------
  251 /**
  252  * Set handler called when server disconnection is detected.
  253  *
  254  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  255  * to continue without exiting, it should call longjmp() from inside the handler.
  256  */
  257 //--------------------------------------------------------------------------------------------------
  258 void le_avc_SetServerDisconnectHandler
  259 (
  260     le_avc_DisconnectHandler_t disconnectHandler,
  261     void *contextPtr
  262 );
  263 
  264 //--------------------------------------------------------------------------------------------------
  265 /**
  266  *
  267  * Disconnect the current client thread from the service providing this API.
  268  *
  269  * Normally, this function doesn't need to be called. After this function is called, there's no
  270  * longer a connection to the service, and the functions in this API can't be used. For details, see
  271  * @ref apiFilesC_client.
  272  *
  273  * This function is created automatically.
  274  */
  275 //--------------------------------------------------------------------------------------------------
  276 void le_avc_DisconnectService
  277 (
  278     void
  279 );
  280 
  281 
  282 //--------------------------------------------------------------------------------------------------
  283 /**
  284  * Maximum APN name length without NULL terminator.
  285  */
  286 //--------------------------------------------------------------------------------------------------
  287 #define LE_AVC_APN_NAME_MAX_LEN 48
  288 
  289 //--------------------------------------------------------------------------------------------------
  290 /**
  291  * Maximum APN name length including NULL terminator.
  292  */
  293 //--------------------------------------------------------------------------------------------------
  294 #define LE_AVC_APN_NAME_MAX_LEN_BYTES 49
  295 
  296 //--------------------------------------------------------------------------------------------------
  297 /**
  298  * Maximum user name length without NULL terminator.
  299  */
  300 //--------------------------------------------------------------------------------------------------
  301 #define LE_AVC_USERNAME_MAX_LEN 28
  302 
  303 //--------------------------------------------------------------------------------------------------
  304 /**
  305  * Maximum user name length including NULL terminator.
  306  */
  307 //--------------------------------------------------------------------------------------------------
  308 #define LE_AVC_USERNAME_MAX_LEN_BYTES 29
  309 
  310 //--------------------------------------------------------------------------------------------------
  311 /**
  312  * Maximum password length without NULL terminator..
  313  */
  314 //--------------------------------------------------------------------------------------------------
  315 #define LE_AVC_PASSWORD_MAX_LEN 28
  316 
  317 //--------------------------------------------------------------------------------------------------
  318 /**
  319  * Maximum password length including NULL terminator.
  320  */
  321 //--------------------------------------------------------------------------------------------------
  322 #define LE_AVC_PASSWORD_MAX_LEN_BYTES 29
  323 
  324 //--------------------------------------------------------------------------------------------------
  325 /**
  326  * Maximum number of retry timers.
  327  */
  328 //--------------------------------------------------------------------------------------------------
  329 #define LE_AVC_NUM_RETRY_TIMERS 8
  330 
  331 //--------------------------------------------------------------------------------------------------
  332 /**
  333  *  Polling timer value range in minutes. 525600 minutes = 1 year.
  334  */
  335 //--------------------------------------------------------------------------------------------------
  336 #define LE_AVC_POLLING_TIMER_MAX_VAL 525600
  337 
  338 //--------------------------------------------------------------------------------------------------
  339 /**
  340  */
  341 //--------------------------------------------------------------------------------------------------
  342 #define LE_AVC_POLLING_TIMER_MIN_VAL 0
  343 
  344 //--------------------------------------------------------------------------------------------------
  345 /**
  346  *  Retry timer value range in minutes. 20160 minutes = 2 weeks.
  347  */
  348 //--------------------------------------------------------------------------------------------------
  349 #define LE_AVC_RETRY_TIMER_MAX_VAL 20160
  350 
  351 //--------------------------------------------------------------------------------------------------
  352 /**
  353  */
  354 //--------------------------------------------------------------------------------------------------
  355 #define LE_AVC_RETRY_TIMER_MIN_VAL 0
  356 
  357 //--------------------------------------------------------------------------------------------------
  358 /**
  359  * Default HTTP status.
  360  */
  361 //--------------------------------------------------------------------------------------------------
  362 #define LE_AVC_HTTP_STATUS_INVALID 65535
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  * Status of session or update
  367  *
  368  * If an update is pending, it must first be downloaded and then installed.
  369  */
  370 //--------------------------------------------------------------------------------------------------
  371 typedef enum
  372 {
  373     LE_AVC_NO_UPDATE = 0,
  374         ///< No updates pending
  375     LE_AVC_DOWNLOAD_PENDING = 1,
  376         ///< Update pending download
  377     LE_AVC_DOWNLOAD_IN_PROGRESS = 2,
  378         ///< Download in progress
  379     LE_AVC_DOWNLOAD_COMPLETE = 3,
  380         ///< Download has completed
  381     LE_AVC_DOWNLOAD_FAILED = 4,
  382         ///< An error occurred downloading the update
  383     LE_AVC_INSTALL_PENDING = 5,
  384         ///< Install is pending (implies download complete)
  385     LE_AVC_INSTALL_IN_PROGRESS = 6,
  386         ///< Install in progress
  387     LE_AVC_INSTALL_COMPLETE = 7,
  388         ///< Update has been successfully installed
  389     LE_AVC_INSTALL_FAILED = 8,
  390         ///< An error occurred installing the update
  391     LE_AVC_UNINSTALL_PENDING = 9,
  392         ///< Uninstall is pending
  393     LE_AVC_UNINSTALL_IN_PROGRESS = 10,
  394         ///< Uninstall in progress
  395     LE_AVC_UNINSTALL_COMPLETE = 11,
  396         ///< App has been successfully uninstalled
  397     LE_AVC_UNINSTALL_FAILED = 12,
  398         ///< An error occurred uninstalling the update
  399     LE_AVC_SESSION_STARTED = 13,
  400         ///< Session with AV server started
  401     LE_AVC_SESSION_STOPPED = 14,
  402         ///< Session with AV server stopped
  403     LE_AVC_REBOOT_PENDING = 15,
  404         ///< Device reboot is pending
  405     LE_AVC_CONNECTION_REQUIRED = 16
  406         ///< Connection to the server is required
  407 }
  408 le_avc_Status_t;
  409 
  410 
  411 //--------------------------------------------------------------------------------------------------
  412 /**
  413  * Request to open or close avms session.
  414  */
  415 //--------------------------------------------------------------------------------------------------
  416 typedef enum
  417 {
  418     LE_AVC_SESSION_ACQUIRE = 0,
  419         ///< Request by user app to open AV session
  420     LE_AVC_SESSION_RELEASE = 1
  421         ///< Request by user app to close AV session
  422 }
  423 le_avc_SessionRequest_t;
  424 
  425 
  426 //--------------------------------------------------------------------------------------------------
  427 /**
  428  * The type of pending update
  429  */
  430 //--------------------------------------------------------------------------------------------------
  431 typedef enum
  432 {
  433     LE_AVC_UNKNOWN_UPDATE = 0,
  434         ///<
  435     LE_AVC_FIRMWARE_UPDATE = 1,
  436         ///<
  437     LE_AVC_FRAMEWORK_UPDATE = 2,
  438         ///<
  439     LE_AVC_APPLICATION_UPDATE = 3
  440         ///<
  441 }
  442 le_avc_UpdateType_t;
  443 
  444 
  445 //--------------------------------------------------------------------------------------------------
  446 /**
  447  * Error code used to provide diagnostic information after a failure (includes both download and
  448  * install failure).
  449  *
  450  * @note
  451  *     Additional information may also be available in the target device's system log.
  452  */
  453 //--------------------------------------------------------------------------------------------------
  454 typedef enum
  455 {
  456     LE_AVC_ERR_NONE = 0,
  457         ///< No error.
  458     LE_AVC_ERR_BAD_PACKAGE = 1,
  459         ///< Encountered a bad package.
  460     LE_AVC_ERR_INTERNAL = 2,
  461         ///< Something failed while doing install/download.
  462     LE_AVC_ERR_SECURITY_FAILURE = 3
  463         ///< Security check failure while installing the package.
  464 }
  465 le_avc_ErrorCode_t;
  466 
  467 
  468 //--------------------------------------------------------------------------------------------------
  469 /**
  470  * Session type indicates whether the device is connected to the bootstrap server or the
  471  * device management server.
  472  */
  473 //--------------------------------------------------------------------------------------------------
  474 typedef enum
  475 {
  476     LE_AVC_BOOTSTRAP_SESSION = 0,
  477         ///< Bootstrap session.
  478     LE_AVC_DM_SESSION = 1,
  479         ///< Device Management session.
  480     LE_AVC_SESSION_INVALID = 2
  481         ///< Session type invalid.
  482 }
  483 le_avc_SessionType_t;
  484 
  485 
  486 //--------------------------------------------------------------------------------------------------
  487 /**
  488  * Reference type used by Add/Remove functions for EVENT 'le_avc_StatusEvent'
  489  */
  490 //--------------------------------------------------------------------------------------------------
  491 typedef struct le_avc_StatusEventHandler* le_avc_StatusEventHandlerRef_t;
  492 
  493 
  494 //--------------------------------------------------------------------------------------------------
  495 /**
  496  * Reference type used by Add/Remove functions for EVENT 'le_avc_SessionRequestEvent'
  497  */
  498 //--------------------------------------------------------------------------------------------------
  499 typedef struct le_avc_SessionRequestEventHandler* le_avc_SessionRequestEventHandlerRef_t;
  500 
  501 
  502 //--------------------------------------------------------------------------------------------------
  503 /**
  504  * Reference returned by BlockInstall function and used by UnblockInstall function
  505  */
  506 //--------------------------------------------------------------------------------------------------
  507 typedef struct le_avc_BlockRequest* le_avc_BlockRequestRef_t;
  508 
  509 
  510 //--------------------------------------------------------------------------------------------------
  511 /**
  512  * Handler for update availability status
  513  */
  514 //--------------------------------------------------------------------------------------------------
  515 typedef void (*le_avc_StatusHandlerFunc_t)
  516 (
  517     le_avc_Status_t updateStatus,
  518         ///< status of pending update, if available
  519     int32_t totalNumBytes,
  520         ///< Total number of bytes to be downloaded
  521         ///< only valid when updateStatus is one of
  522         ///< DOWNLOAD_PENDING, DOWNLOAD_IN_PROGRESS or DOWNLOAD_COMPLETE.
  523         ///< returns -1 if value is unknown
  524     int32_t dloadProgress,
  525         ///< download completion in percentage
  526         ///< only valid when updateStatus is one of
  527         ///< DOWNLOAD_PENDING, DOWNLOAD_IN_PROGRESS or DOWNLOAD_COMPLETE.
  528         ///< returns -1 if value is unknown
  529     void* contextPtr
  530         ///<
  531 );
  532 
  533 //--------------------------------------------------------------------------------------------------
  534 /**
  535  * Handler for receiving session open or close request.
  536  */
  537 //--------------------------------------------------------------------------------------------------
  538 typedef void (*le_avc_SessionRequestHandlerFunc_t)
  539 (
  540     le_avc_SessionRequest_t request,
  541         ///< Request to open or close AV session
  542     void* contextPtr
  543         ///<
  544 );
  545 
  546 //--------------------------------------------------------------------------------------------------
  547 /**
  548  * Add handler function for EVENT 'le_avc_StatusEvent'
  549  *
  550  * This event provides information on update availability status
  551  */
  552 //--------------------------------------------------------------------------------------------------
  553 le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler
  554 (
  555     le_avc_StatusHandlerFunc_t handlerPtr,
  556         ///< [IN]
  557     void* contextPtr
  558         ///< [IN]
  559 );
  560 
  561 //--------------------------------------------------------------------------------------------------
  562 /**
  563  * Remove handler function for EVENT 'le_avc_StatusEvent'
  564  */
  565 //--------------------------------------------------------------------------------------------------
  566 void le_avc_RemoveStatusEventHandler
  567 (
  568     le_avc_StatusEventHandlerRef_t handlerRef
  569         ///< [IN]
  570 );
  571 
  572 //--------------------------------------------------------------------------------------------------
  573 /**
  574  * Add handler function for EVENT 'le_avc_SessionRequestEvent'
  575  *
  576  * This event provides information on session open or close request.
  577  */
  578 //--------------------------------------------------------------------------------------------------
  579 le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler
  580 (
  581     le_avc_SessionRequestHandlerFunc_t handlerPtr,
  582         ///< [IN]
  583     void* contextPtr
  584         ///< [IN]
  585 );
  586 
  587 //--------------------------------------------------------------------------------------------------
  588 /**
  589  * Remove handler function for EVENT 'le_avc_SessionRequestEvent'
  590  */
  591 //--------------------------------------------------------------------------------------------------
  592 void le_avc_RemoveSessionRequestEventHandler
  593 (
  594     le_avc_SessionRequestEventHandlerRef_t handlerRef
  595         ///< [IN]
  596 );
  597 
  598 //--------------------------------------------------------------------------------------------------
  599 /**
  600  * Start a session with the AirVantage server
  601  *
  602  * This will cause a query to be sent to the server, for pending updates. If a download was
  603  * previously suspended, then this resumes the download.
  604  *
  605  * @return
  606  *      - LE_OK if connection request has been sent.
  607  *      - LE_FAULT on failure
  608  *      - LE_DUPLICATE if already connected.
  609  *      - LE_BUSY if currently retrying.
  610  */
  611 //--------------------------------------------------------------------------------------------------
  612 le_result_t le_avc_StartSession
  613 (
  614     void
  615 );
  616 
  617 //--------------------------------------------------------------------------------------------------
  618 /**
  619  * Stop a session with the AirVantage server
  620  *
  621  * If a download is in progress, then this suspends the download.
  622  *
  623  * @return
  624  *      - LE_OK on success
  625  *      - LE_FAULT on failure
  626  */
  627 //--------------------------------------------------------------------------------------------------
  628 le_result_t le_avc_StopSession
  629 (
  630     void
  631 );
  632 
  633 //--------------------------------------------------------------------------------------------------
  634 /**
  635  * Send a specific message to the server to be sure that the route between the device and the server
  636  * is available.
  637  * This API needs to be called when any package download is over (successfully or not) and before
  638  * sending any notification on asset data to the server.
  639  *
  640  * @return
  641  *      - LE_OK when the treatment is launched
  642  *      - LE_FAULT on failure
  643  *      - LE_UNSUPPORTED when the API is not supported
  644  *
  645  */
  646 //--------------------------------------------------------------------------------------------------
  647 le_result_t le_avc_CheckRoute
  648 (
  649     void
  650 );
  651 
  652 //--------------------------------------------------------------------------------------------------
  653 /**
  654  * Accept the currently pending download
  655  *
  656  * @return
  657  *      - LE_OK on success
  658  *      - LE_FAULT on failure
  659  */
  660 //--------------------------------------------------------------------------------------------------
  661 le_result_t le_avc_AcceptDownload
  662 (
  663     void
  664 );
  665 
  666 //--------------------------------------------------------------------------------------------------
  667 /**
  668  * Defer the currently pending download, for the given number of minutes
  669  *
  670  * @return
  671  *      - LE_OK on success
  672  *      - LE_FAULT on failure
  673  */
  674 //--------------------------------------------------------------------------------------------------
  675 le_result_t le_avc_DeferDownload
  676 (
  677     uint32_t deferMinutes
  678         ///< [IN]
  679 );
  680 
  681 //--------------------------------------------------------------------------------------------------
  682 /**
  683  * Accept the currently pending install
  684  *
  685  * @return
  686  *      - LE_OK on success
  687  *      - LE_FAULT on failure
  688  */
  689 //--------------------------------------------------------------------------------------------------
  690 le_result_t le_avc_AcceptInstall
  691 (
  692     void
  693 );
  694 
  695 //--------------------------------------------------------------------------------------------------
  696 /**
  697  * Defer the currently pending install
  698  *
  699  * @return
  700  *      - LE_OK on success
  701  *      - LE_FAULT on failure
  702  */
  703 //--------------------------------------------------------------------------------------------------
  704 le_result_t le_avc_DeferInstall
  705 (
  706     uint32_t deferMinutes
  707         ///< [IN]
  708 );
  709 
  710 //--------------------------------------------------------------------------------------------------
  711 /**
  712  * Accept the currently pending uninstall
  713  *
  714  * @return
  715  *      - LE_OK on success
  716  *      - LE_FAULT on failure
  717  */
  718 //--------------------------------------------------------------------------------------------------
  719 le_result_t le_avc_AcceptUninstall
  720 (
  721     void
  722 );
  723 
  724 //--------------------------------------------------------------------------------------------------
  725 /**
  726  * Defer the currently pending uninstall
  727  *
  728  * @return
  729  *      - LE_OK on success
  730  *      - LE_FAULT on failure
  731  */
  732 //--------------------------------------------------------------------------------------------------
  733 le_result_t le_avc_DeferUninstall
  734 (
  735     uint32_t deferMinutes
  736         ///< [IN]
  737 );
  738 
  739 //--------------------------------------------------------------------------------------------------
  740 /**
  741  * Accept the currently pending reboot
  742  *
  743  * @return
  744  *      - LE_OK on success
  745  *      - LE_FAULT on failure
  746  */
  747 //--------------------------------------------------------------------------------------------------
  748 le_result_t le_avc_AcceptReboot
  749 (
  750     void
  751 );
  752 
  753 //--------------------------------------------------------------------------------------------------
  754 /**
  755  * Defer the currently pending reboot
  756  *
  757  * @return
  758  *      - LE_OK on success
  759  *      - LE_FAULT on failure
  760  */
  761 //--------------------------------------------------------------------------------------------------
  762 le_result_t le_avc_DeferReboot
  763 (
  764     uint32_t deferMinutes
  765         ///< [IN]
  766 );
  767 
  768 //--------------------------------------------------------------------------------------------------
  769 /**
  770  * Get the update type of the currently pending update
  771  *
  772  * @return
  773  *      - LE_OK on success
  774  *      - LE_FAULT if not available
  775  */
  776 //--------------------------------------------------------------------------------------------------
  777 le_result_t le_avc_GetUpdateType
  778 (
  779     le_avc_UpdateType_t* updateTypePtr
  780         ///< [OUT]
  781 );
  782 
  783 //--------------------------------------------------------------------------------------------------
  784 /**
  785  * Get the name for the currently pending app update
  786  *
  787  * @return
  788  *      - LE_OK on success
  789  *      - LE_FAULT if not available, or isn't APPL_UPDATE type
  790  */
  791 //--------------------------------------------------------------------------------------------------
  792 le_result_t le_avc_GetAppUpdateName
  793 (
  794     char* updateName,
  795         ///< [OUT]
  796     size_t updateNameSize
  797         ///< [IN]
  798 );
  799 
  800 //--------------------------------------------------------------------------------------------------
  801 /**
  802  * Prevent any pending updates from being installed.
  803  *
  804  * @return
  805  *      - Reference for block update request (to be used later for unblocking updates)
  806  *      - NULL if the operation was not successful
  807  */
  808 //--------------------------------------------------------------------------------------------------
  809 le_avc_BlockRequestRef_t le_avc_BlockInstall
  810 (
  811     void
  812 );
  813 
  814 //--------------------------------------------------------------------------------------------------
  815 /**
  816  * Allow any pending updates to be installed
  817  */
  818 //--------------------------------------------------------------------------------------------------
  819 void le_avc_UnblockInstall
  820 (
  821     le_avc_BlockRequestRef_t blockRef
  822         ///< [IN] block request ref returned by le_avc_BlockInstall
  823 );
  824 
  825 //--------------------------------------------------------------------------------------------------
  826 /**
  827  * Function to get error code when update fails.
  828  *
  829  * @return
  830  *      - Error code of encountered error.
  831  *      - ERR_NONE if update is in any other state.
  832  */
  833 //--------------------------------------------------------------------------------------------------
  834 le_avc_ErrorCode_t le_avc_GetErrorCode
  835 (
  836     void
  837 );
  838 
  839 //--------------------------------------------------------------------------------------------------
  840 /**
  841  * Function to read the current session type, or the last session type if there is no
  842  * active session.
  843  *
  844  * @return
  845  *      - SessionType
  846  */
  847 //--------------------------------------------------------------------------------------------------
  848 le_avc_SessionType_t le_avc_GetSessionType
  849 (
  850     void
  851 );
  852 
  853 //--------------------------------------------------------------------------------------------------
  854 /**
  855  * Function to read the http status of the last download.
  856  *
  857  * @return
  858  *      - HttpStatus as defined in RFC 7231, Section 6.
  859  */
  860 //--------------------------------------------------------------------------------------------------
  861 uint16_t le_avc_GetHttpStatus
  862 (
  863     void
  864 );
  865 
  866 //--------------------------------------------------------------------------------------------------
  867 /**
  868  * Function to read the polling timer.
  869  *
  870  * @return
  871  *      - LE_OK on success
  872  *      - LE_FAULT if not available
  873  *      - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
  874  */
  875 //--------------------------------------------------------------------------------------------------
  876 le_result_t le_avc_GetPollingTimer
  877 (
  878     uint32_t* pollingTimerPtr
  879         ///< [OUT] Polling timer
  880 );
  881 
  882 //--------------------------------------------------------------------------------------------------
  883 /**
  884  * Function to read the retry timers.
  885  *
  886  * @return
  887  *      - LE_OK on success.
  888  *      - LE_FAULT if not able to read the timers.
  889  *      - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
  890  */
  891 //--------------------------------------------------------------------------------------------------
  892 le_result_t le_avc_GetRetryTimers
  893 (
  894     uint16_t* timerValuePtr,
  895         ///< [OUT] Array of the retry timers.
  896     size_t* timerValueSizePtr
  897         ///< [INOUT]
  898 );
  899 
  900 //--------------------------------------------------------------------------------------------------
  901 /**
  902  * Function to read APN configuration.
  903  *
  904  * @return
  905  *      - LE_OK on success.
  906  *      - LE_FAULT if there is any error while reading.
  907  *      - LE_OVERFLOW if the buffer provided is too small.
  908  */
  909 //--------------------------------------------------------------------------------------------------
  910 le_result_t le_avc_GetApnConfig
  911 (
  912     char* apnName,
  913         ///< [OUT]
  914     size_t apnNameSize,
  915         ///< [IN]
  916     char* userName,
  917         ///< [OUT]
  918     size_t userNameSize,
  919         ///< [IN]
  920     char* userPwd,
  921         ///< [OUT]
  922     size_t userPwdSize
  923         ///< [IN]
  924 );
  925 
  926 //--------------------------------------------------------------------------------------------------
  927 /**
  928  * Function to write APN configuration.
  929  *
  930  * @return
  931  *      - LE_OK on success.
  932  *      - LE_OVERFLOW if one of the input strings is too long.
  933  */
  934 //--------------------------------------------------------------------------------------------------
  935 le_result_t le_avc_SetApnConfig
  936 (
  937     const char* apnName,
  938         ///< [IN]
  939     const char* userName,
  940         ///< [IN]
  941     const char* userPwd
  942         ///< [IN]
  943 )
  944 __attribute__(( nonnull(1,2,3) ));
  945 
  946 //--------------------------------------------------------------------------------------------------
  947 /**
  948  * Function to set the polling timer.
  949  *
  950  * @return
  951  *      - LE_OK on success.
  952  *      - LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
  953  */
  954 //--------------------------------------------------------------------------------------------------
  955 le_result_t le_avc_SetPollingTimer
  956 (
  957     uint32_t pollingTimer
  958         ///< [IN] Polling timer
  959 );
  960 
  961 //--------------------------------------------------------------------------------------------------
  962 /**
  963  * Function to set the retry timers.
  964  *
  965  * @return
  966  *      - LE_OK on success.
  967  *      - LE_FAULT if not able to set the timers.
  968  *      - LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
  969  */
  970 //--------------------------------------------------------------------------------------------------
  971 le_result_t le_avc_SetRetryTimers
  972 (
  973     const uint16_t* timerValuePtr,
  974         ///< [IN] Array of 8 retry timers.
  975     size_t timerValueSize
  976         ///< [IN]
  977 );
  978 
  979 #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:393
le_avc_SetApnConfig
le_result_t le_avc_SetApnConfig(const char *apnName, const char *userName, const char *userPwd)
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:516
LE_AVC_UNINSTALL_PENDING
Uninstall is pending. 
Definition: le_avc_interface.h:391
LE_AVC_SESSION_RELEASE
Request by user app to close AV session. 
Definition: le_avc_interface.h:420
LE_AVC_INSTALL_FAILED
An error occurred installing the update. 
Definition: le_avc_interface.h:389
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_result_t
le_result_t
Definition: le_basics.h:35
le_avc_SessionRequestHandlerFunc_t
void(* le_avc_SessionRequestHandlerFunc_t)(le_avc_SessionRequest_t request, void *contextPtr)
Definition: le_avc_interface.h:539
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:397
LE_AVC_INSTALL_IN_PROGRESS
Install in progress. 
Definition: le_avc_interface.h:385
le_avc_UnblockInstall
void le_avc_UnblockInstall(le_avc_BlockRequestRef_t blockRef)
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:499
le_avc_SessionRequest_t
le_avc_SessionRequest_t
Definition: le_avc_interface.h:416
LE_AVC_DOWNLOAD_FAILED
An error occurred downloading the update. 
Definition: le_avc_interface.h:381
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:383
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:205
LE_AVC_SESSION_STOPPED
Session with AV server stopped. 
Definition: le_avc_interface.h:401
LE_AVC_SESSION_STARTED
Session with AV server started. 
Definition: le_avc_interface.h:399
le_avc_SessionType_t
le_avc_SessionType_t
Definition: le_avc_interface.h:474
LE_AVC_DOWNLOAD_IN_PROGRESS
Download in progress. 
Definition: le_avc_interface.h:377
LE_AVC_REBOOT_PENDING
Device reboot is pending. 
Definition: le_avc_interface.h:403
LE_AVC_SESSION_INVALID
Session type invalid. 
Definition: le_avc_interface.h:480
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_DOWNLOAD_PENDING
Update pending download. 
Definition: le_avc_interface.h:375
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_CONNECTION_REQUIRED
Connection to the server is required. 
Definition: le_avc_interface.h:405
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:387
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:460
LE_AVC_BOOTSTRAP_SESSION
Bootstrap session. 
Definition: le_avc_interface.h:476
le_avc_BlockRequestRef_t
struct le_avc_BlockRequest * le_avc_BlockRequestRef_t
Definition: le_avc_interface.h:507
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_DM_SESSION
Device Management session. 
Definition: le_avc_interface.h:478
LE_AVC_ERR_NONE
No error. 
Definition: le_avc_interface.h:456
legato.h
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:431
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:462
LE_AVC_SESSION_ACQUIRE
Request by user app to open AV session. 
Definition: le_avc_interface.h:418
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:454
LE_AVC_DOWNLOAD_COMPLETE
Download has completed. 
Definition: le_avc_interface.h:379
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:373
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:491
LE_AVC_ERR_BAD_PACKAGE
Encountered a bad package. 
Definition: le_avc_interface.h:458
le_avc_Status_t
le_avc_Status_t
Definition: le_avc_interface.h:371
LE_AVC_UNINSTALL_COMPLETE
App has been successfully uninstalled. 
Definition: le_avc_interface.h:395
le_avc_GetErrorCode
le_avc_ErrorCode_t le_avc_GetErrorCode(void)
le_avc_ConnectService
void le_avc_ConnectService(void)