le_update_common.h - Legato Docs

Go to the documentation of this file.
    1 
    2 /*
    3  * ====================== WARNING ======================
    4  *
    5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    6  * DO NOT MODIFY IN ANY WAY.
    7  *
    8  * ====================== WARNING ======================
    9  */
   10 /**
   11  * @file le_update_common.h
   12  *
   13  * Type definitions for le_update.
   14  *
   15  */
   16 #ifndef LE_UPDATE_COMMON_H_INCLUDE_GUARD
   17 #define LE_UPDATE_COMMON_H_INCLUDE_GUARD
   18 
   19 
   20 #include "legato.h"
   21 
   22 // Interface specific includes
   23 #include "le_limit_common.h"
   24 
   25 #define IFGEN_LE_UPDATE_PROTOCOL_ID "17cd65c5c26efb8f22650432980df70f"
   26 #define IFGEN_LE_UPDATE_MSG_SIZE 48
   27 /** @addtogroup le_update
   28  *  @{ **/
   29 
   30 
   31 //--------------------------------------------------------------------------------------------------
   32 /**
   33  * Different states in the update state machine. The state machine is maintained to track the
   34  * update task underway.
   35  *
   36  * Example:
   37  *     for successful installation task, state transitions look like:
   38  *
   39  *@verbatim
   40     --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
   41             |                                 |
   42             +---------------------------------+-------> FAILED.
   43 @endverbatim
   44  */
   45 //--------------------------------------------------------------------------------------------------
   46 typedef enum
   47 {
   48     LE_UPDATE_STATE_UNPACKING = 0,
   49         ///< Unpacking update data.
   50     LE_UPDATE_STATE_DOWNLOAD_SUCCESS = 1,
   51         ///< Update data downloaded successfully.
   52     LE_UPDATE_STATE_APPLYING = 2,
   53         ///< Applying update(i.e. installation/removal operation going on).
   54     LE_UPDATE_STATE_SUCCESS = 3,
   55         ///< Successfully completed all update task.
   56     LE_UPDATE_STATE_FAILED = 4
   57         ///< Update failed due to some error or deletion request.
   58 }
   59 le_update_State_t;
   60 
   61 
   62 //--------------------------------------------------------------------------------------------------
   63 /**
   64  * Error code used to provide diagnostic information after a failed update.
   65  *
   66  * @note
   67  *     Additional information may also be available in the target device's system log.
   68  */
   69 //--------------------------------------------------------------------------------------------------
   70 typedef enum
   71 {
   72     LE_UPDATE_ERR_NONE = 0,
   73         ///< No error.
   74     LE_UPDATE_ERR_BAD_PACKAGE = 1,
   75         ///< Encountered bad update package. Check logs.
   76     LE_UPDATE_ERR_INTERNAL_ERROR = 2,
   77         ///< Something failed while doing update.  Check logs.
   78     LE_UPDATE_ERR_SECURITY_FAILURE = 3
   79         ///< Error while doing security check of the package.
   80 }
   81 le_update_ErrorCode_t;
   82 
   83 
   84 //--------------------------------------------------------------------------------------------------
   85 /**
   86  * Reference type used by Add/Remove functions for EVENT 'le_update_Progress'
   87  */
   88 //--------------------------------------------------------------------------------------------------
   89 typedef struct le_update_ProgressHandler* le_update_ProgressHandlerRef_t;
   90 
   91 
   92 //--------------------------------------------------------------------------------------------------
   93 /**
   94  * The client callback function (handler) passed to le_update_Start() must look like this.
   95  */
   96 //--------------------------------------------------------------------------------------------------
   97 typedef void (*le_update_ProgressHandlerFunc_t)
   98 (
   99         le_update_State_t updateState,
  100         ///< Current state of update.
  101         uint32_t percentDone,
  102         ///< Percent done for current state. For example, in state
  103         ///< UNPACKING, a percentDone of 80 means that 80% of the update
  104         ///< data has been unpacked.
  105         void* contextPtr
  106         ///<
  107 );
  108 
  109 
  110 //--------------------------------------------------------------------------------------------------
  111 /**
  112  * Get if this client bound locally.
  113  */
  114 //--------------------------------------------------------------------------------------------------
  115 LE_SHARED bool ifgen_le_update_HasLocalBinding
  116 (
  117     void
  118 );
  119 
  120 
  121 //--------------------------------------------------------------------------------------------------
  122 /**
  123  * Init data that is common across all threads
  124  */
  125 //--------------------------------------------------------------------------------------------------
  126 LE_SHARED void ifgen_le_update_InitCommonData
  127 (
  128     void
  129 );
  130 
  131 
  132 //--------------------------------------------------------------------------------------------------
  133 /**
  134  * Perform common initialization and open a session
  135  */
  136 //--------------------------------------------------------------------------------------------------
  137 LE_SHARED le_result_t ifgen_le_update_OpenSession
  138 (
  139     le_msg_SessionRef_t _ifgen_sessionRef,
  140     bool isBlocking
  141 );
  142 
  143 //--------------------------------------------------------------------------------------------------
  144 /**
  145  * Add handler function for EVENT 'le_update_Progress'
  146  *
  147  * Register for notification of the progress of a given update.
  148  */
  149 //--------------------------------------------------------------------------------------------------
  150 LE_SHARED le_update_ProgressHandlerRef_t ifgen_le_update_AddProgressHandler
  151 (
  152     le_msg_SessionRef_t _ifgen_sessionRef,
  153         le_update_ProgressHandlerFunc_t handlerPtr,
  154         ///< [IN] Progress handler
  155         void* contextPtr
  156         ///< [IN]
  157 );
  158 
  159 //--------------------------------------------------------------------------------------------------
  160 /**
  161  * Remove handler function for EVENT 'le_update_Progress'
  162  */
  163 //--------------------------------------------------------------------------------------------------
  164 LE_SHARED void ifgen_le_update_RemoveProgressHandler
  165 (
  166     le_msg_SessionRef_t _ifgen_sessionRef,
  167         le_update_ProgressHandlerRef_t handlerRef
  168         ///< [IN]
  169 );
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  * Starts an update.
  174  *
  175  * Progress is reported via the progress handler callback.
  176  *
  177  * @return
  178  *      - LE_OK if accepted.
  179  *      - LE_BUSY if another update is in progress.
  180  *      - LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).
  181  */
  182 //--------------------------------------------------------------------------------------------------
  183 LE_SHARED le_result_t ifgen_le_update_Start
  184 (
  185     le_msg_SessionRef_t _ifgen_sessionRef,
  186         int fd
  187         ///< [IN] Open file descriptor from which the update can be read.
  188 );
  189 
  190 //--------------------------------------------------------------------------------------------------
  191 /**
  192  * Install the update
  193  *
  194  * @return
  195  *      - LE_OK if installation started.
  196  *      - LE_BUSY if package download is not finished yet.
  197  *      - LE_FAULT if there is an error. Check logs
  198  */
  199 //--------------------------------------------------------------------------------------------------
  200 LE_SHARED le_result_t ifgen_le_update_Install
  201 (
  202     le_msg_SessionRef_t _ifgen_sessionRef
  203 );
  204 
  205 //--------------------------------------------------------------------------------------------------
  206 /**
  207  * Ends an update session.  If the update isn't finished yet, cancels it.
  208  */
  209 //--------------------------------------------------------------------------------------------------
  210 LE_SHARED void ifgen_le_update_End
  211 (
  212     le_msg_SessionRef_t _ifgen_sessionRef
  213 );
  214 
  215 //--------------------------------------------------------------------------------------------------
  216 /**
  217  * Function to get error code when update fails.
  218  *
  219  * @return
  220  *      - Error code of encountered error.
  221  *      - ERR_NONE if update is in any other state.
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 LE_SHARED le_update_ErrorCode_t ifgen_le_update_GetErrorCode
  225 (
  226     le_msg_SessionRef_t _ifgen_sessionRef
  227 );
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  * Get the index of the currently running system.
  232  *
  233  * @return The index of the running system.
  234  */
  235 //--------------------------------------------------------------------------------------------------
  236 LE_SHARED int32_t ifgen_le_update_GetCurrentSysIndex
  237 (
  238     le_msg_SessionRef_t _ifgen_sessionRef
  239 );
  240 
  241 //--------------------------------------------------------------------------------------------------
  242 /**
  243  * Gets the hash ID for a given system.
  244  *
  245  * @return
  246  *      - LE_OK if no problems are encountered.
  247  *      - LE_NOT_FOUND if the given index does not correspond to an available system.
  248  *      - LE_OVERFLOW if the supplied buffer is too small.
  249  *      - LE_FORMAT_ERROR if there are problems reading the hash for the system.
  250  */
  251 //--------------------------------------------------------------------------------------------------
  252 LE_SHARED le_result_t ifgen_le_update_GetSystemHash
  253 (
  254     le_msg_SessionRef_t _ifgen_sessionRef,
  255         int32_t systemIndex,
  256         ///< [IN] The system to read the hash for.
  257         char* hashStr,
  258         ///< [OUT] Buffer to hold the system hash string.
  259         size_t hashStrSize
  260         ///< [IN]
  261 );
  262 
  263 //--------------------------------------------------------------------------------------------------
  264 /**
  265  * Get the index for the previous system in the chain, using the current system as a starting point.
  266  *
  267  * @return The index to the system that's previous to the given system.  -1 is returned if the
  268  *         previous system was not found.
  269  */
  270 //--------------------------------------------------------------------------------------------------
  271 LE_SHARED int32_t ifgen_le_update_GetPreviousSystemIndex
  272 (
  273     le_msg_SessionRef_t _ifgen_sessionRef,
  274         int32_t systemIndex
  275         ///< [IN] Get the system that's older than this system.
  276 );
  277 /** @} **/
  278 #endif // LE_UPDATE_COMMON_H_INCLUDE_GUARD
le_update_ErrorCode_t
le_update_ErrorCode_t
Definition: le_update_common.h:70
le_update_State_t
le_update_State_t
Definition: le_update_common.h:46
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:300
le_result_t
le_result_t
Definition: le_basics.h:46
LE_UPDATE_ERR_BAD_PACKAGE
Encountered bad update package. Check logs. 
Definition: le_update_common.h:74
LE_UPDATE_ERR_SECURITY_FAILURE
Error while doing security check of the package. 
Definition: le_update_common.h:78
LE_UPDATE_STATE_APPLYING
Applying update(i.e. installation/removal operation going on). 
Definition: le_update_common.h:52
LE_UPDATE_ERR_INTERNAL_ERROR
Something failed while doing update. Check logs. 
Definition: le_update_common.h:76
LE_UPDATE_STATE_SUCCESS
Successfully completed all update task. 
Definition: le_update_common.h:54
le_limit_common.h
LE_UPDATE_STATE_DOWNLOAD_SUCCESS
Update data downloaded successfully. 
Definition: le_update_common.h:50
LE_UPDATE_STATE_FAILED
Update failed due to some error or deletion request. 
Definition: le_update_common.h:56
le_msg_SessionRef_t
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860
legato.h
LE_UPDATE_ERR_NONE
No error. 
Definition: le_update_common.h:72
LE_UPDATE_STATE_UNPACKING
Unpacking update data. 
Definition: le_update_common.h:48
le_update_ProgressHandlerFunc_t
void(* le_update_ProgressHandlerFunc_t)(le_update_State_t updateState, uint32_t percentDone, void *contextPtr)
Definition: le_update_common.h:98
le_update_ProgressHandlerRef_t
struct le_update_ProgressHandler * le_update_ProgressHandlerRef_t
Definition: le_update_common.h:89