le_update_common.h File Reference

#include "legato.h"
#include "le_limit_common.h"

Go to the source code of this file.

Macros
#define	IFGEN_LE_UPDATE_PROTOCOL_ID   "17cd65c5c26efb8f22650432980df70f"
#define	IFGEN_LE_UPDATE_MSG_SIZE   48

Typedefs
typedef struct le_update_ProgressHandler *	le_update_ProgressHandlerRef_t
typedef void(*	le_update_ProgressHandlerFunc_t) (le_update_State_t updateState, uint32_t percentDone, void *contextPtr)

Enumerations
enum	le_update_State_t {   LE_UPDATE_STATE_UNPACKING = 0, LE_UPDATE_STATE_DOWNLOAD_SUCCESS = 1, LE_UPDATE_STATE_APPLYING = 2, LE_UPDATE_STATE_SUCCESS = 3,   LE_UPDATE_STATE_FAILED = 4 }
enum	le_update_ErrorCode_t { LE_UPDATE_ERR_NONE = 0, LE_UPDATE_ERR_BAD_PACKAGE = 1, LE_UPDATE_ERR_INTERNAL_ERROR = 2, LE_UPDATE_ERR_SECURITY_FAILURE = 3 }

Functions
LE_SHARED bool	ifgen_le_update_HasLocalBinding (void)
LE_SHARED void	ifgen_le_update_InitCommonData (void)
LE_SHARED void	ifgen_le_update_CleanupCommonData (le_msg_SessionRef_t _ifgen_sessionRef)
LE_SHARED le_result_t	ifgen_le_update_OpenSession (le_msg_SessionRef_t _ifgen_sessionRef, bool isBlocking)
LE_SHARED le_update_ProgressHandlerRef_t	ifgen_le_update_AddProgressHandler (le_msg_SessionRef_t _ifgen_sessionRef, le_update_ProgressHandlerFunc_t handlerPtr, void *contextPtr)
LE_SHARED void	ifgen_le_update_RemoveProgressHandler (le_msg_SessionRef_t _ifgen_sessionRef, le_update_ProgressHandlerRef_t handlerRef)
LE_SHARED le_result_t	ifgen_le_update_Start (le_msg_SessionRef_t _ifgen_sessionRef, int fd)
LE_SHARED le_result_t	ifgen_le_update_Install (le_msg_SessionRef_t _ifgen_sessionRef)
LE_SHARED void	ifgen_le_update_End (le_msg_SessionRef_t _ifgen_sessionRef)
LE_SHARED le_update_ErrorCode_t	ifgen_le_update_GetErrorCode (le_msg_SessionRef_t _ifgen_sessionRef)
LE_SHARED int32_t	ifgen_le_update_GetCurrentSysIndex (le_msg_SessionRef_t _ifgen_sessionRef)
LE_SHARED le_result_t	ifgen_le_update_GetSystemHash (le_msg_SessionRef_t _ifgen_sessionRef, int32_t systemIndex, char *hashStr, size_t hashStrSize)
LE_SHARED int32_t	ifgen_le_update_GetPreviousSystemIndex (le_msg_SessionRef_t _ifgen_sessionRef, int32_t systemIndex)

Macro Definition Documentation

IFGEN_LE_UPDATE_PROTOCOL_ID

#define IFGEN_LE_UPDATE_PROTOCOL_ID   "17cd65c5c26efb8f22650432980df70f"

IFGEN_LE_UPDATE_MSG_SIZE

#define IFGEN_LE_UPDATE_MSG_SIZE   48

Typedef Documentation

le_update_ProgressHandlerRef_t

typedef struct le_update_ProgressHandler* le_update_ProgressHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_update_Progress'

le_update_ProgressHandlerFunc_t

typedef void(* le_update_ProgressHandlerFunc_t) (le_update_State_t updateState, uint32_t percentDone, void *contextPtr)

The client callback function (handler) passed to le_update_Start() must look like this.

Enumeration Type Documentation

le_update_State_t

enum le_update_State_t

Different states in the update state machine. The state machine is maintained to track the update task underway.

Example: for successful installation task, state transitions look like:

    --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
            |                                 |
            +---------------------------------+-------> FAILED.

Enumerator
LE_UPDATE_STATE_UNPACKING	Unpacking update data.
LE_UPDATE_STATE_DOWNLOAD_SUCCESS	Update data downloaded successfully.
LE_UPDATE_STATE_APPLYING	Applying update(i.e. installation/removal operation going on).
LE_UPDATE_STATE_SUCCESS	Successfully completed all update task.
LE_UPDATE_STATE_FAILED	Update failed due to some error or deletion request.

le_update_ErrorCode_t

enum le_update_ErrorCode_t

Error code used to provide diagnostic information after a failed update.

Note

Additional information may also be available in the target device's system log.

Enumerator
LE_UPDATE_ERR_NONE	No error.
LE_UPDATE_ERR_BAD_PACKAGE	Encountered bad update package. Check logs.
LE_UPDATE_ERR_INTERNAL_ERROR	Something failed while doing update. Check logs.
LE_UPDATE_ERR_SECURITY_FAILURE	Error while doing security check of the package.

Function Documentation

ifgen_le_update_HasLocalBinding()

LE_SHARED bool ifgen_le_update_HasLocalBinding

(

void

)

Get if this client bound locally.

ifgen_le_update_InitCommonData()

LE_SHARED void ifgen_le_update_InitCommonData

(

void

)

Init data that is common across all threads

ifgen_le_update_CleanupCommonData()

LE_SHARED void ifgen_le_update_CleanupCommonData

(

le_msg_SessionRef_t

_ifgen_sessionRef

)

Cleanup the data of a session

ifgen_le_update_OpenSession()

LE_SHARED le_result_t ifgen_le_update_OpenSession	(	le_msg_SessionRef_t	_ifgen_sessionRef,
		bool	isBlocking
	)

Perform common initialization and open a session

ifgen_le_update_AddProgressHandler()

LE_SHARED le_update_ProgressHandlerRef_t ifgen_le_update_AddProgressHandler	(	le_msg_SessionRef_t	_ifgen_sessionRef,
		le_update_ProgressHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

Add handler function for EVENT 'le_update_Progress'

Register for notification of the progress of a given update.

Parameters

[in]	handlerPtr	Progress handler
[in]	contextPtr

ifgen_le_update_RemoveProgressHandler()

LE_SHARED void ifgen_le_update_RemoveProgressHandler	(	le_msg_SessionRef_t	_ifgen_sessionRef,
		le_update_ProgressHandlerRef_t	handlerRef
	)

Remove handler function for EVENT 'le_update_Progress'

Parameters

[in]

handlerRef

ifgen_le_update_Start()

LE_SHARED le_result_t ifgen_le_update_Start	(	le_msg_SessionRef_t	_ifgen_sessionRef,
		int	fd
	)

Starts an update.

Progress is reported via the progress handler callback.

Returns

• LE_OK if accepted.
• LE_BUSY if another update is in progress.
• LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).

Parameters

[in]

fd

Open file descriptor from which the update can be read.

ifgen_le_update_Install()

LE_SHARED le_result_t ifgen_le_update_Install

(

le_msg_SessionRef_t

_ifgen_sessionRef

)

Install the update

Returns

• LE_OK if installation started.
• LE_BUSY if package download is not finished yet.
• LE_FAULT if there is an error. Check logs

ifgen_le_update_End()

LE_SHARED void ifgen_le_update_End

(

le_msg_SessionRef_t

_ifgen_sessionRef

)

Ends an update session. If the update isn't finished yet, cancels it.

ifgen_le_update_GetErrorCode()

LE_SHARED le_update_ErrorCode_t ifgen_le_update_GetErrorCode

(

le_msg_SessionRef_t

_ifgen_sessionRef

)

Function to get error code when update fails.

Returns

• Error code of encountered error.
• ERR_NONE if update is in any other state.

ifgen_le_update_GetCurrentSysIndex()

LE_SHARED int32_t ifgen_le_update_GetCurrentSysIndex

(

le_msg_SessionRef_t

_ifgen_sessionRef

)

Get the index of the currently running system.

Returns

The index of the running system.

ifgen_le_update_GetSystemHash()

LE_SHARED le_result_t ifgen_le_update_GetSystemHash	(	le_msg_SessionRef_t	_ifgen_sessionRef,
		int32_t	systemIndex,
		char *	hashStr,
		size_t	hashStrSize
	)

Gets the hash ID for a given system.

Returns

• LE_OK if no problems are encountered.
• LE_NOT_FOUND if the given index does not correspond to an available system.
• LE_OVERFLOW if the supplied buffer is too small.
• LE_FORMAT_ERROR if there are problems reading the hash for the system.

Parameters

[in]	systemIndex	The system to read the hash for.
[out]	hashStr	Buffer to hold the system hash string.
[in]	hashStrSize

ifgen_le_update_GetPreviousSystemIndex()

LE_SHARED int32_t ifgen_le_update_GetPreviousSystemIndex	(	le_msg_SessionRef_t	_ifgen_sessionRef,
		int32_t	systemIndex
	)

Get the index for the previous system in the chain, using the current system as a starting point.

Returns

The index to the system that's previous to the given system. -1 is returned if the previous system was not found.

Parameters

[in]

systemIndex

Get the system that's older than this system.