nl::Weave::DeviceLayer::SoftwareUpdateManager

Summary

Inheritance

Direct Known Subclasses:
  nl::Weave::DeviceLayer::SoftwareUpdateManagerImpl
  nl::Weave::DeviceLayer::SoftwareUpdateManagerImpl
  nl::Weave::DeviceLayer::SoftwareUpdateManagerImpl

Public types
ActionType{
  kAction_Ignore,
  kAction_DownloadNow,
  kAction_DownloadLater,
  kAction_ApplicationManaged
} 		enum
When a software update is available, the application can chose one of the following actions as part of the SoftwareUpdateAvailable API event callback.
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
EventType{
  kEvent_PrepareQuery,
  kEvent_PrepareQuery_Metadata,
  kEvent_QueryPrepareFailed,
  kEvent_QuerySent,
  kEvent_SoftwareUpdateAvailable,
  kEvent_FetchPartialImageInfo,
  kEvent_PrepareImageStorage,
  kEvent_StartImageDownload,
  kEvent_StoreImageBlock,
  kEvent_ComputeImageIntegrity,
  kEvent_ResetPartialImageInfo,
  kEvent_ReadyToInstall,
  kEvent_StartInstallImage,
  kEvent_Finished,
  kEvent_DefaultCheck = 100
} 		enum
API events generated by the SoftwareUpdateManager object.
RetryPolicyCallback)(void *aAppState, RetryParam &aRetryParam, uint32_t &aOutIntervalMsec) typedef
void(*
State enum

Friend classes
Internal::GenericPlatformManagerImpl
friend class

Public functions
Abort(void)
CheckNow(void)
GetState(void)
State
ImageInstallComplete(WEAVE_ERROR aError)
IsInProgress(void)
bool
PrepareImageStorageComplete(WEAVE_ERROR aError)
SetEventCallback(void *const aAppState, const EventCallback aEventCallback)
SetQueryIntervalWindow(uint32_t aMinWaitTimeMs, uint32_t aMaxWaitTimeMs)
SetRetryPolicyCallback(const RetryPolicyCallback aRetryPolicyCallback)
void

Public static functions
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void

Protected functions
SoftwareUpdateManager()=default
SoftwareUpdateManager(const SoftwareUpdateManager &)=delete
SoftwareUpdateManager(const SoftwareUpdateManager &&)=delete
operator=(const SoftwareUpdateManager &)=delete
~SoftwareUpdateManager()=default

Structs
nl::Weave::DeviceLayer::SoftwareUpdateManager::RetryParam

Unions
nl::Weave::DeviceLayer::SoftwareUpdateManager::InEventParam
nl::Weave::DeviceLayer::SoftwareUpdateManager::OutEventParam

Public types

ActionType

 ActionType

When a software update is available, the application can chose one of the following actions as part of the SoftwareUpdateAvailable API event callback.

The default action will be set to kAction_Now.

Properties
kAction_ApplicationManaged

Allows application to manage the rest of the phases of software update such as download, image integrity validation and install.

Software update manager state machine will move to the ApplicationManaged state. Scheduled software update checks (if enabled) will be suspended till application calls Abort or ImageInstallComplete API.

kAction_DownloadLater

Pause download on start.

Scheduled software update checks (if enabled) will be suspended. State machine will remain in Download state. When ready, application can call the resume download API to proceed with download or call Abort to cancel.

kAction_DownloadNow

Start the download right away.

A kEvent_FetchPartialImageInfo API event callback will be generated right after.

kAction_Ignore

Ignore the download completely.

A kEvent_Finished API event callback will be generated with error WEAVE_DEVICE_ERROR_SOFTWARE_UPDATE_CANCELLED if this option is selected and the retry logic will not be invoked.

EventCallback

void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)

EventType

 EventType

API events generated by the SoftwareUpdateManager object.

Properties
kEvent_ComputeImageIntegrity

Compute an image integrity check value.

Requests the application to compute an integrity check value over the downloaded image. Generated once downloading is complete.

kEvent_DefaultCheck

Check default event handling behavior.

Used to verify correct default event handling in the application.

Applications must NOT handle this event.

kEvent_FetchPartialImageInfo

Fetch persisted state information for a partially downloaded image.

Provides an opportunity for the application to disclose information of a partial image previously downloaded so that the download may be continued from the point where it last stopped. URI of the available software update is provided as an input parameter that the application can use to compare if the image being downloaded is the same as the partial image.

The application is expected to return the length of the partial image in the PartialImageLenInBytes output parameter. The application can set the value of PartialImageLenInBytes to 0 to indicate that no partial image exists or that the URI of the partial image does not match.

The application may choose to ignore this event by passing it to the default event handler. If this is done, the system will always download the entirety of the available firmware image.

kEvent_Finished

Software update process finished.

Generated when a software update check has finished with or without errors. Parameters included with this event provide the reason for failure if the attempt finished due to a failure.

kEvent_PrepareImageStorage

Prepare for storage of a new image.

Requests the application to perform any steps necessary to prepare local storage for the download of a new firmware image. The application can use this, for example, to erase flash pages.

The PrepareImageStorage event is generated only in the case where a new firmware image is being downloaded. When a previously interrupted download is resumed, PrepareImageStorage is not generated.

The application must signal completion of the prepare operation by calling the PrepareImageStorageComplete() method. It may do this within the event callback itself, or at a later time. If called from a task other than the Weave task, the caller must hold the Weave stack lock.

The application can choose to ignore the PrepareImageStorage event by passing it to the default event handler. If this is done, the system automatically proceeds to the image download state.

To support resuming an interrupted download, the application should persist the image URI (supplied as an event parameter), and use this when handling subsequent FetchPartialImageInfo events.

kEvent_PrepareQuery

Prepare ImageQuery message.

Generated when a software update check has been triggered. Provides an opportunity for the application to supply product related information to the SofwareUpdate:ImageQuery message.

kEvent_PrepareQuery_Metadata

Prepare meta-data for ImageQuery request.

Provides an opportunity for the application to append additional meta-data to the SofwareUpdate:ImageQuery message if needed. Generated when implementation is ready to get meta-data from the application.

kEvent_QueryPrepareFailed

Error preparing an ImageQuery request.

Generated when the implementation encounters an error while preparing to send out a software update query.

kEvent_QuerySent

ImageQuery request has been sent.

Informational event to signal that a SofwareUpdate:ImageQuery message has been sent.

kEvent_ReadyToInstall

Image is ready to be installed.

Informational event to signal that image is ready to be installed. Generated once an image passes the integrity check.

kEvent_ResetPartialImageInfo

Reset state of partially downloaded image.

Requests the application to forget the persisted state associated with a downloaded image. A ResetPartialImageInfo event is generated whenever a downloaded image fails its integrity check. After a ResetPartialImageInfo event has been processed, subsequent FetchPartialImageInfo events should indicate that no partial image is available.

Note that, when handling the ResetPartialImageInfo event, the application is NOT required to clear image data itself, only the state information associated with the image (i.e. the URI and partial image length).

If the application does not support image download resumption, it may ignore this event by passing it to the default event handler.

kEvent_SoftwareUpdateAvailable

Software update is available.

Generated when a SofwareUpdate:ImageQueryResponse is received in response to a query containing information of the available update.

kEvent_StartImageDownload

Image download has begun.

Informational event to signal the start of an image download transaction.

kEvent_StartInstallImage

Begin image installation.

Requests the application to being the process of installing a downloaded firmware image.

kEvent_StoreImageBlock

Store a block of image data.

Generated whenever a data block is received from the file download server. Parameters included with this event provide the data and the length of the data.

To support resuming an interrupted download, the application should maintain a persistent count of the total number of image bytes stored, and use this value when handling subsequent FetchPartialImageInfo events.

RetryPolicyCallback

void(* RetryPolicyCallback)(void *aAppState, RetryParam &aRetryParam, uint32_t &aOutIntervalMsec)

State

 State

Friend classes

Internal::GenericPlatformManagerImpl

friend class Internal::GenericPlatformManagerImpl

Public functions

Abort

WEAVE_ERROR Abort(
  void
)

CheckNow

WEAVE_ERROR CheckNow(
  void
)

GetState

State GetState(
  void
)

ImageInstallComplete

WEAVE_ERROR ImageInstallComplete(
  WEAVE_ERROR aError
)

IsInProgress

bool IsInProgress(
  void
)

PrepareImageStorageComplete

WEAVE_ERROR PrepareImageStorageComplete(
  WEAVE_ERROR aError
)

SetEventCallback

WEAVE_ERROR SetEventCallback(
  void *const aAppState,
  const EventCallback aEventCallback
)

SetQueryIntervalWindow

WEAVE_ERROR SetQueryIntervalWindow(
  uint32_t aMinWaitTimeMs,
  uint32_t aMaxWaitTimeMs
)

SetRetryPolicyCallback

void SetRetryPolicyCallback(
  const RetryPolicyCallback aRetryPolicyCallback
)

Public static functions

DefaultEventHandler

void DefaultEventHandler(
  void *apAppState,
  EventType aEvent,
  const InEventParam & aInParam,
  OutEventParam & aOutParam
)

Protected functions

SoftwareUpdateManager

 SoftwareUpdateManager()=default

SoftwareUpdateManager

 SoftwareUpdateManager(
  const SoftwareUpdateManager &
)=delete

SoftwareUpdateManager

 SoftwareUpdateManager(
  const SoftwareUpdateManager &&
)=delete

operator=

SoftwareUpdateManager & operator=(
  const SoftwareUpdateManager &
)=delete

~SoftwareUpdateManager

 ~SoftwareUpdateManager()=default