le_update_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

Macros
#define	LE_UPDATE_ID_STR_LEN   64

Typedefs
typedef struct le_update_Handle *	le_update_HandleRef_t
typedef struct le_update_ProgressHandler *	le_update_ProgressHandlerRef_t
typedef void(*	le_update_ProgressHandlerFunc_t) (le_update_State_t updateState, uint percentDone, void *contextPtr)

Enumerations
enum	le_update_Command_t { LE_UPDATE_CMD_INSTALL, LE_UPDATE_CMD_REMOVE }
enum	le_update_ItemType_t { LE_UPDATE_APP, LE_UPDATE_FIRMWARE }
enum	le_update_State_t {   LE_UPDATE_STATE_NEW, LE_UPDATE_STATE_UNPACKING, LE_UPDATE_STATE_APPLYING, LE_UPDATE_STATE_SUCCESS,   LE_UPDATE_STATE_FAILED }
enum	le_update_ErrorCode_t {   LE_UPDATE_ERR_NONE, LE_UPDATE_ERR_BAD_MANIFEST, LE_UPDATE_ERR_IO_ERROR, LE_UPDATE_ERR_INTERNAL_ERROR,   LE_UPDATE_ERR_OUT_OF_MEMORY, LE_UPDATE_ERR_VERSION_MISMATCH, LE_UPDATE_ERR_WRONG_TARGET }

Functions
void	le_update_ConnectService (void)
void	le_update_DisconnectService (void)
le_update_HandleRef_t	le_update_Create (int fileDesc)
le_result_t	le_update_Start (le_update_HandleRef_t handle)
void	le_update_Delete (le_update_HandleRef_t handle)
le_update_ErrorCode_t	le_update_GetErrorCode (le_update_HandleRef_t handle)
le_update_ProgressHandlerRef_t	le_update_AddProgressHandler (le_update_HandleRef_t handle, le_update_ProgressHandlerFunc_t handlerPtr, void *contextPtr)
void	le_update_RemoveProgressHandler (le_update_ProgressHandlerRef_t addHandlerRef)

Detailed Description

Legato Software Update include file.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

Macro Definition Documentation

#define LE_UPDATE_ID_STR_LEN   64

Length of the ID string. ID string is used to identify update item underway, e.g. for app update/remove ID string will contain appName, for firmware it will contain firmware version.

Typedef Documentation

typedef struct le_update_Handle* le_update_HandleRef_t

Reference to update task. Used to identify an update task.

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

Client callback function to notify status of underway update task.

Parameters

updateState	Current State of underway update process in state machine.
percentDone	Percent done for current state. As example: at state LE_UPDATE_STATE_UNPACKING, percentDone=80 means, 80% of the update file data is already transferred to unpack process.
contextPtr

typedef struct le_update_ProgressHandler* le_update_ProgressHandlerRef_t

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

Enumeration Type Documentation

enum le_update_Command_t

Supported commands inside manifest.

Note

Subject to change.

Enumerator
LE_UPDATE_CMD_INSTALL	Install tasks. This includes installation of apps, firmware.
LE_UPDATE_CMD_REMOVE	Removal tasks. This includes removal of apps.

enum le_update_ErrorCode_t

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

Note

Subject to change.

Enumerator
LE_UPDATE_ERR_NONE	No error.
LE_UPDATE_ERR_BAD_MANIFEST	Found bad manifest in supplied update package.
LE_UPDATE_ERR_IO_ERROR	Encountered IO error.
LE_UPDATE_ERR_INTERNAL_ERROR	Something wrong happened while doing update.
LE_UPDATE_ERR_OUT_OF_MEMORY	Not enough memory available to install update.
LE_UPDATE_ERR_VERSION_MISMATCH	Software version mismatch.
LE_UPDATE_ERR_WRONG_TARGET	Detected wrong target.

enum le_update_ItemType_t

Supported platform types to be updated (inside manifest).

Note

Subject to change.

Enumerator
LE_UPDATE_APP	App item.
LE_UPDATE_FIRMWARE	Firmware item.

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: STATE_NEW–>STATE_UNPACKING–>STATE_APPLYING–>STATE_SUCCESS.

Note

Subject to change.

Enumerator
LE_UPDATE_STATE_NEW	Requested new update task.
LE_UPDATE_STATE_UNPACKING	Unpacking update data.
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.

Function Documentation

le_update_ProgressHandlerRef_t le_update_AddProgressHandler	(	le_update_HandleRef_t	handle,
		le_update_ProgressHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

Add handler function for EVENT 'le_update_Progress'

Shows the status of the underway update process.

Parameters

[in]	handle	Update object reference.
[in]	handlerPtr
[in]	contextPtr

void le_update_ConnectService

(

void

)

Connect the client to the service

le_update_HandleRef_t le_update_Create

(

int

fileDesc

)

Creates an update handle. This handle needs to be used in subsequent api calls.

Returns

• Null if already an update is going on.
• Handle reference if successful.

Parameters

[in]

fileDesc

File descriptor containing the update package.

void le_update_Delete

(

le_update_HandleRef_t

handle

)

Deletes an update task that's underway. Either deletes the update task (if safe) or marks to delete it after current update current task is finished. If manifest contains multiple update items, all of the subsequent update items are cancelled as part of deletion process.

Note

The handle becomes invalid after it has been deleted..

Parameters

[in]

handle

Handle of the underway update task.

void le_update_DisconnectService

(

void

)

Disconnect the client from the service

le_update_ErrorCode_t le_update_GetErrorCode

(

le_update_HandleRef_t

handle

)

Function to get error code when update fails.

Returns

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

Parameters

[in]

handle

Handle of the underway update task.

void le_update_RemoveProgressHandler

(

le_update_ProgressHandlerRef_t

addHandlerRef

)

Remove handler function for EVENT 'le_update_Progress'

Parameters

[in]

addHandlerRef

le_result_t le_update_Start

(

le_update_HandleRef_t

handle

)

Starts update process(i.e. parsing manifest, doing update as per manifest). This is an asynchronous function (it returns after the update process has started, but doesn't verify if it finishes). Client will get status through registered call back function.

Returns

• LE_OK if update starts successfully.
• LE_FAULT if update failed to start.

Parameters

[in]

handle

Handle of requested update task.