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