le_update_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

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_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_FORMAT_ERROR, 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 Update API include file.

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

Typedef Documentation

typedef struct le_update_Handle* le_update_HandleRef_t

Reference to an update task.

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

The client callback function (handler) registered using le_update_AddProgressHandler() must look like this.

Parameters

updateState	Current state of update.
percentDone	Percent done for current state. For example, in state UNPACKING, a percentDone of 80 means that 80% of the update data has been unpacked.
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_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_FORMAT_ERROR	The supplied update package was not properly constructed.
LE_UPDATE_ERR_IO_ERROR	Encountered IO error.
LE_UPDATE_ERR_INTERNAL_ERROR	Something failed while doing update. Check logs.
LE_UPDATE_ERR_OUT_OF_MEMORY	Not enough memory available to install update.
LE_UPDATE_ERR_VERSION_MISMATCH	Update depends on software not installed on target.
LE_UPDATE_ERR_WRONG_TARGET	Attempted to install update on wrong type of target device.

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:

    NEW --> UNPACKING --> APPLYING --> SUCCESS.

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'

Register for notification of the progress of a given update.

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 handle. If the update is not finished yet, cancels it.

Note

The handle becomes invalid after it has been deleted.

Parameters

[in]

handle

Handle of the 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 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.

Status will be reported through calls to the callback function registered using le_update_AddProgressHandler().

Returns

• LE_OK if successful.
• LE_FAULT if update failed immediately.

Parameters

[in]

handle

Handle of requested update task.