le_updateCtrl_interface.h

    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_updateCtrl Update Control API
   12  *
   13  * @ref le_updateCtrl_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * This API is used by privileged apps to control the software update process.  It can be used to:
   18  * - prevent updates from happening or
   19  * - control the marking of a system update as "good" or "bad".
   20  *
   21  * Note that this is not part of the Update API (le_update) because the
   22  * Update API can be used by less trusted apps to feed signed/encrypted updates to the
   23  * Update Daemon, and we may not trust those same apps to have the ability to prevent someone
   24  * else from updating or rolling-back the system.
   25  *
   26  *
   27  * @section le_updateCtrl_prevention Preventing Updates During Critical Operations
   28  *
   29  * To protect against updates during critical periods of operation (such as when performing an
   30  * emergency call in response to a vehicle collision), the following functions are provided:
   31  *
   32  * - le_updateCtrl_Defer() - prevent all updates until further notice.
   33  * - le_updateCtrl_Allow() - allow updates to go ahead.
   34  *
   35  * Updates will not be allowed to go ahead until no clients are deferring updates. So, if client A
   36  * and client B both call le_updateCtrl_Defer(), updates will be deferred until both client A and
   37  * client B have called le_updateCtrl_Allow().
   38  *
   39  * le_updateCtrl_Defer() will also prevent rollbacks unless a fault triggers the Supervisor to
   40  * restart the framework or reboot the target.  See below for more information on rollbacks.
   41  *
   42  *
   43  * @section le_updateCtrl_probation Controlling the Probation Period
   44  *
   45  * Whenever a new system is started, a probation period begins.  If the system stays running for
   46  * the entire probation period, the system is marked "good".  But, during the probation period,
   47  * if an app faults enough times in a short enough period for the Supervisor to give up on trying
   48  * to start it, the system update is marked "bad" and the system is rolled-back to the last known
   49  * "good" system.
   50  *
   51  * In some cases, a customer may want to extend the probation period of their new system for a
   52  * non-deterministic amount of time, until it has had a chance to perform some action in the
   53  * real world (such as successfully "phoning home" at least once).
   54  *
   55  * To support this, the functions le_updateCtrl_LockProbation() and le_updateCtrl_UnlockProbation()
   56  * are provided, where each call to "Lock" must be matched with a call to "Unlock".
   57  *
   58  * For those who want to mark "good" at some point of their own determination, regardless
   59  * of how long the system has been up, le_updateCtrl_MarkGood() is provided.
   60  *
   61  * And for those who want to mark the system "bad" and trigger a rollback at some point of
   62  * their own choosing, le_updateCtrl_FailProbation() is provided.
   63  *
   64  * Calls to any of the functions that affect the probation period are ignored if the probation
   65  * period is already over (if the system is already marked "good"). Once it is "good", it stays
   66  * "good".
   67  *
   68  * If someone tries to update the system while it is still in its probation period, the update
   69  * will be refused.  To override this, call le_updateCtrl_FailProbation() or
   70  * le_updateCtrl_MarkGood() to end the probation period before trying to apply the new
   71  * system update.
   72  *
   73  * @note If a reboot occurs during the probation period, the probation period will start over.
   74  * But, if the system reboots more than a few times without reaching the end of its probation
   75  * period first, then the system will be rolled-back to the last known "good" system.
   76  *
   77  * <HR>
   78  *
   79  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   80  */
   81 /**
   82  * @file le_updateCtrl_interface.h
   83  *
   84  * Legato @ref c_updateCtrl include file.
   85  *
   86  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   87  */
   88 
   89 #ifndef LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
   90 #define LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
   91 
   92 
   93 #include "legato.h"
   94 
   95 //--------------------------------------------------------------------------------------------------
   96 /**
   97  *
   98  * Connect the current client thread to the service providing this API. Block until the service is
   99  * available.
  100  *
  101  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  102  * called before any other functions in this API.  Normally, ConnectService is automatically called
  103  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  104  *
  105  * This function is created automatically.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 void le_updateCtrl_ConnectService
  109 (
  110     void
  111 );
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Try to connect the current client thread to the service providing this API. Return with an error
  117  * if the service is not available.
  118  *
  119  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  120  * called before any other functions in this API.  Normally, ConnectService is automatically called
  121  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  122  *
  123  * This function is created automatically.
  124  *
  125  * @return
  126  *  - LE_OK if the client connected successfully to the service.
  127  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  128  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  129  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  130  */
  131 //--------------------------------------------------------------------------------------------------
  132 le_result_t le_updateCtrl_TryConnectService
  133 (
  134     void
  135 );
  136 
  137 //--------------------------------------------------------------------------------------------------
  138 /**
  139  *
  140  * Disconnect the current client thread from the service providing this API.
  141  *
  142  * Normally, this function doesn't need to be called. After this function is called, there's no
  143  * longer a connection to the service, and the functions in this API can't be used. For details, see
  144  * @ref apiFilesC_client.
  145  *
  146  * This function is created automatically.
  147  */
  148 //--------------------------------------------------------------------------------------------------
  149 void le_updateCtrl_DisconnectService
  150 (
  151     void
  152 );
  153 
  154 //--------------------------------------------------------------------------------------------------
  155 /**
  156  * Prevent all updates (and roll-backs) until further notice.
  157  */
  158 //--------------------------------------------------------------------------------------------------
  159 void le_updateCtrl_Defer
  160 (
  161     void
  162 );
  163 
  164 //--------------------------------------------------------------------------------------------------
  165 /**
  166  * Allow updates to go ahead.
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 void le_updateCtrl_Allow
  170 (
  171     void
  172 );
  173 
  174 //--------------------------------------------------------------------------------------------------
  175 /**
  176  * Prevent the probation period from ending.
  177  *
  178  * @note Ignored if the probation period has already ended.
  179  */
  180 //--------------------------------------------------------------------------------------------------
  181 void le_updateCtrl_LockProbation
  182 (
  183     void
  184 );
  185 
  186 //--------------------------------------------------------------------------------------------------
  187 /**
  188  * Cancels a call to LockProbation(), allow the probation period to end.
  189  *
  190  * @note Ignored if the probation period has already ended.
  191  */
  192 //--------------------------------------------------------------------------------------------------
  193 void le_updateCtrl_UnlockProbation
  194 (
  195     void
  196 );
  197 
  198 //--------------------------------------------------------------------------------------------------
  199 /**
  200  * Marks the system "good", ending the probation period.
  201  *
  202  * @return
  203  *      - LE_OK         The system was marked Good
  204  *      - LE_BUSY       Someone holds a probation lock
  205  *      - LE_DUPLICATE  Probation has expired - the system has already been marked
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 le_result_t le_updateCtrl_MarkGood
  209 (
  210     bool force
  211         ///< [IN] True to set system Good even if someone holds a probation lock
  212 );
  213 
  214 //--------------------------------------------------------------------------------------------------
  215 /**
  216  * Marks the system "bad" and triggers a roll-back to a "good" system.
  217  *
  218  * @note Ignored if the probation period has already ended.  Also, the roll-back may be delayed if
  219  * someone is deferring updates using le_updateCtrl_Defer().
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 void le_updateCtrl_FailProbation
  223 (
  224     void
  225 );
  226 
  227 
  228 #endif // LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
  229 
le_updateCtrl_FailProbation
void le_updateCtrl_FailProbation(void)
le_result_t
le_result_t
Definition: le_basics.h:35
le_updateCtrl_DisconnectService
void le_updateCtrl_DisconnectService(void)
le_updateCtrl_ConnectService
void le_updateCtrl_ConnectService(void)
le_updateCtrl_UnlockProbation
void le_updateCtrl_UnlockProbation(void)
le_updateCtrl_TryConnectService
le_result_t le_updateCtrl_TryConnectService(void)
le_updateCtrl_Defer
void le_updateCtrl_Defer(void)
le_updateCtrl_MarkGood
le_result_t le_updateCtrl_MarkGood(bool force)
legato.h
le_updateCtrl_LockProbation
void le_updateCtrl_LockProbation(void)
le_updateCtrl_Allow
void le_updateCtrl_Allow(void)