src/adaptations/device-layer/include/Weave/DeviceLayer/SoftwareUpdateManager.h - third_party/openweave-core - Git at Google

 /*
  *
  *    Copyright (c) 2019 Google LLC.
  *    All rights reserved.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
  *    You may obtain a copy of the License at
  *
  *        http://www.apache.org/licenses/LICENSE-2.0
  *
  *    Unless required by applicable law or agreed to in writing, software
  *    distributed under the License is distributed on an "AS IS" BASIS,
  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *    See the License for the specific language governing permissions and
  *    limitations under the License.
  */

 /**
  *    @file
  *          Defines the public interface for the Device Layer SoftwareUpdateManager object.
  */

 #ifndef SOFTWARE_UPDATE_MANAGER_H
 #define SOFTWARE_UPDATE_MANAGER_H

 #if WEAVE_DEVICE_CONFIG_ENABLE_SOFTWARE_UPDATE_MANAGER

 #include <Weave/Profiles/software-update/SoftwareUpdateProfile.h>
 #include <Weave/DeviceLayer/internal/WeaveDeviceLayerInternal.h>

 namespace nl {
 namespace Weave {
 namespace DeviceLayer {

 class SoftwareUpdateManagerImpl;

 class SoftwareUpdateManager
 {
     typedef ::nl::Weave::TLV::TLVWriter TLVWriter;
     typedef ::nl::Weave::Profiles::SoftwareUpdate::UpdatePriority UpdatePriority;
     typedef ::nl::Weave::Profiles::SoftwareUpdate::UpdateCondition UpdateCondition;

     using ImplClass = SoftwareUpdateManagerImpl;


 public:

     // ===== Members that define the public interface of the SoftwareUpdateManager

     enum State
     {
         kState_Idle                 = 1,
         kState_ScheduledHoldoff     = 2,
         kState_PrepareQuery         = 3,
         kState_Query                = 4,
         kState_PrepareImageStorage  = 5,
         kState_Download             = 6,
         kState_Install              = 7,

         kState_ApplicationManaged   = 8,

         kState_MaxState
     };

     /**
      * API events generated by the \c SoftwareUpdateManager object.
      */
     enum EventType
     {
         /**
          *  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,

         /**
          *  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_PrepareQuery_Metadata,

         /**
          *  Error preparing an ImageQuery request
          *
          *  Generated when the implementation encounters an error while preparing to send out
          *  a software update query.
          */
         kEvent_QueryPrepareFailed,

         /**
          *  ImageQuery request has been sent
          *
          *  Informational event to signal that a SofwareUpdate:ImageQuery message has been sent.
          */
         kEvent_QuerySent,

         /**
          *  Software update is available
          *
          *  Generated when a SofwareUpdate:ImageQueryResponse is received in response to
          *  a query containing information of the available update.
          */
         kEvent_SoftwareUpdateAvailable,

         /**
          *  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_FetchPartialImageInfo,

         /**
          *  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
          *  \c 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_PrepareImageStorage,

         /**
          *  Image download has begun
          *
          *  Informational event to signal the start of an image download transaction.
          */
         kEvent_StartImageDownload,

         /**
          *  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.
          */
         kEvent_StoreImageBlock,

         /**
          *  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_ComputeImageIntegrity,

         /**
          *  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_ResetPartialImageInfo,

         /**
          *  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_ReadyToInstall,

         /**
          *  Begin image installation
          *
          *  Requests the application to being the process of installing a downloaded firmware
          *  image.
          */
         kEvent_StartInstallImage,

         /**
          *  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_Finished,

         /**
          *  Check default event handling behavior.
          *
          *  Used to verify correct default event handling in the application.
          *
          *  Applications must NOT handle this event.
          */
         kEvent_DefaultCheck                         = 100,

     };

     /**
      *  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.
      */
     enum ActionType
     {
         /**
          *  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.
          */
         kAction_Ignore,

         /**
          *  Start the download right away. A kEvent_FetchPartialImageInfo API event
          *  callback will be generated right after.
          */
         kAction_DownloadNow,

         /**
          *  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_DownloadLater,

         /**
          *  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_ApplicationManaged,
     };

     /**
      *  Incoming parameters sent with events generated directly from this component
      *
      */
     union InEventParam;

    /**
      *  Outgoing parameters sent with events generated directly from this component
      *
      */
     union OutEventParam;

     struct RetryParam
     {
         /**
          *  Specifies the retry attempt number.
          *  It is reset on a successful software update attempt.
          */
         uint32_t NumRetries;
     };

     typedef void (*EventCallback)(void *apAppState, EventType aEvent, const InEventParam& aInParam, OutEventParam& aOutParam);
     typedef void (*RetryPolicyCallback)(void *aAppState, RetryParam& aRetryParam, uint32_t& aOutIntervalMsec);

     WEAVE_ERROR Abort(void);
     WEAVE_ERROR CheckNow(void);
     WEAVE_ERROR ImageInstallComplete(WEAVE_ERROR aError);
     WEAVE_ERROR PrepareImageStorageComplete(WEAVE_ERROR aError);
     WEAVE_ERROR SetEventCallback(void * const aAppState, const EventCallback aEventCallback);
     WEAVE_ERROR SetQueryIntervalWindow(uint32_t aMinWaitTimeMs, uint32_t aMaxWaitTimeMs);

     bool IsInProgress(void);

     void SetRetryPolicyCallback(const RetryPolicyCallback aRetryPolicyCallback);

     State GetState(void);

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

 private:
     // ===== Members for internal use by the following friends.

     // friend class SoftwareUpdateManagerImpl;
     template<class> friend class Internal::GenericPlatformManagerImpl;

     WEAVE_ERROR Init(void);

 protected:

     // Construction/destruction limited to subclasses.
     SoftwareUpdateManager() = default;
     ~SoftwareUpdateManager() = default;

     // No copy, move or assignment.
     SoftwareUpdateManager(const SoftwareUpdateManager &) = delete;
     SoftwareUpdateManager(const SoftwareUpdateManager &&) = delete;
     SoftwareUpdateManager & operator=(const SoftwareUpdateManager &) = delete;
 };

 /**
  * Returns a reference to the public interface of the SoftwareUpdateManager singleton object.
  *
  * Weave application should use this to access features of the SoftwareUpdateManager object
  * that are common to all platforms.
  */
 extern SoftwareUpdateManager & SoftwareUpdateMgr(void);

 /**
  * Returns the platform-specific implementation of the SoftwareUpdateManager singleton object.
  *
  * Weave applications can use this to gain access to features of the SoftwareUpdateManager
  * that are specific to the selected platform.
  */
 extern SoftwareUpdateManagerImpl & SoftwareUpdateMgrImpl(void);

 } // namespace DeviceLayer
 } // namespace Weave
 } // namespace nl

 /* Include a header file containing the implementation of the SoftwareUpdateManager
  * object for the selected platform.
  */
 #ifdef EXTERNAL_SOFTWAREUPDATEMANAGERIMPL_HEADER
 #include EXTERNAL_SOFTWAREUPDATEMANAGERIMPL_HEADER
 #else
 #define SOFTWAREUPDATEMANAGERIMPL_HEADER <Weave/DeviceLayer/WEAVE_DEVICE_LAYER_TARGET/SoftwareUpdateManagerImpl.h>
 #include SOFTWAREUPDATEMANAGERIMPL_HEADER
 #endif

 namespace nl {
 namespace Weave {
 namespace DeviceLayer {

 union SoftwareUpdateManager::InEventParam
 {
     void Clear(void) { memset(this, 0, sizeof(*this)); }

     SoftwareUpdateManager * Source;
     struct
     {
         TLVWriter * MetaDataWriter;
     } PrepareQuery_Metadata;

     struct
     {
         WEAVE_ERROR Error;
         Profiles::StatusReporting::StatusReport *StatusReport;
     } QueryPrepareFailed;

     struct
     {
         UpdatePriority Priority;
         UpdateCondition Condition;
         uint8_t IntegrityType;
         const char *URI;
         const char *Version;
     } SoftwareUpdateAvailable;

     struct
     {
         const char *URI;
     } FetchPartialImageInfo;

     struct
     {
         const char *URI;
         uint8_t IntegrityType;
     } PrepareImageStorage;

     struct
     {
         uint8_t *DataBlock;
         uint32_t DataBlockLen;
     } StoreImageBlock;

     struct
     {
         uint8_t IntegrityType;
         uint8_t *IntegrityValueBuf;     // Pointer to the buffer for the app to copy Integrity Value into.
         uint8_t IntegrityValueBufLen;   // Length of the provided buffer.
     } ComputeImageIntegrity;

     struct
     {
         WEAVE_ERROR Error;
         Profiles::StatusReporting::StatusReport *StatusReport;
     } Finished;
 };

 union SoftwareUpdateManager::OutEventParam
 {
     void Clear(void) { memset(this, 0, sizeof(*this)); }

     bool DefaultHandlerCalled;
     struct
     {
         const char *PackageSpecification;
         const char *DesiredLocale;
         WEAVE_ERROR Error;
     } PrepareQuery;

     struct
     {
         WEAVE_ERROR Error;
     } PrepareQuery_Metadata;

     struct
     {
         ActionType Action;
     } SoftwareUpdateAvailable;

     struct
     {
         uint64_t PartialImageLen;
     } FetchPartialImageInfo;

     struct
     {
         WEAVE_ERROR Error;
     } StoreImageBlock;

     struct
     {
         WEAVE_ERROR Error;
     } ComputeImageIntegrity;
 };

 inline WEAVE_ERROR SoftwareUpdateManager::Init(void)
 {
     return static_cast<ImplClass*>(this)->_Init();
 }

 inline WEAVE_ERROR SoftwareUpdateManager::CheckNow(void)
 {
     return static_cast<ImplClass*>(this)->_CheckNow();
 }

 inline WEAVE_ERROR SoftwareUpdateManager::ImageInstallComplete(WEAVE_ERROR aError)
 {
     return static_cast<ImplClass*>(this)->_ImageInstallComplete(aError);
 }

 inline WEAVE_ERROR SoftwareUpdateManager::PrepareImageStorageComplete(WEAVE_ERROR aError)
 {
     return static_cast<ImplClass*>(this)->_PrepareImageStorageComplete(aError);
 }

 inline SoftwareUpdateManager::State SoftwareUpdateManager::GetState(void)
 {
     return static_cast<ImplClass*>(this)->_GetState();
 }

 inline WEAVE_ERROR SoftwareUpdateManager::Abort(void)
 {
     return static_cast<ImplClass*>(this)->_Abort();
 }

 inline bool SoftwareUpdateManager::IsInProgress(void)
 {
     return static_cast<ImplClass*>(this)->_IsInProgress();
 }

 inline WEAVE_ERROR SoftwareUpdateManager::SetQueryIntervalWindow(uint32_t aMinRangeSecs, uint32_t aMaxRangeSecs)
 {
     return static_cast<ImplClass*>(this)->_SetQueryIntervalWindow(aMinRangeSecs, aMaxRangeSecs);
 }

 inline void SoftwareUpdateManager::SetRetryPolicyCallback(const RetryPolicyCallback aRetryPolicyCallback)
 {
     static_cast<ImplClass*>(this)->_SetRetryPolicyCallback(aRetryPolicyCallback);
 }

 inline WEAVE_ERROR SoftwareUpdateManager::SetEventCallback(void * const aAppState, const EventCallback aEventCallback)
 {
     return static_cast<ImplClass*>(this)->_SetEventCallback(aAppState, aEventCallback);
 }

 inline void SoftwareUpdateManager::DefaultEventHandler(void *apAppState, EventType aEvent,
                                                        const InEventParam& aInParam,
                                                        OutEventParam& aOutParam)
 {
     ImplClass::_DefaultEventHandler(apAppState, aEvent, aInParam, aOutParam);
 }

 } // namespace DeviceLayer
 } // namespace Weave
 } // namespace nl

 #endif // WEAVE_DEVICE_CONFIG_ENABLE_SOFTWARE_UPDATE_MANAGER
 #endif // SOFTWARE_UPDATE_MANAGER_H
	/*
	*
	* Copyright (c) 2019 Google LLC.
	* All rights reserved.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	/**
	* @file
	* Defines the public interface for the Device Layer SoftwareUpdateManager object.
	*/

	#ifndef SOFTWARE_UPDATE_MANAGER_H
	#define SOFTWARE_UPDATE_MANAGER_H

	#if WEAVE_DEVICE_CONFIG_ENABLE_SOFTWARE_UPDATE_MANAGER

	#include <Weave/Profiles/software-update/SoftwareUpdateProfile.h>
	#include <Weave/DeviceLayer/internal/WeaveDeviceLayerInternal.h>

	namespace nl {
	namespace Weave {
	namespace DeviceLayer {

	class SoftwareUpdateManagerImpl;

	class SoftwareUpdateManager
	{
	typedef ::nl::Weave::TLV::TLVWriter TLVWriter;
	typedef ::nl::Weave::Profiles::SoftwareUpdate::UpdatePriority UpdatePriority;
	typedef ::nl::Weave::Profiles::SoftwareUpdate::UpdateCondition UpdateCondition;

	using ImplClass = SoftwareUpdateManagerImpl;


	public:

	// ===== Members that define the public interface of the SoftwareUpdateManager

	enum State
	{
	kState_Idle = 1,
	kState_ScheduledHoldoff = 2,
	kState_PrepareQuery = 3,
	kState_Query = 4,
	kState_PrepareImageStorage = 5,
	kState_Download = 6,
	kState_Install = 7,

	kState_ApplicationManaged = 8,

	kState_MaxState
	};

	/**
	* API events generated by the \c SoftwareUpdateManager object.
	*/
	enum EventType
	{
	/**
	* 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,

	/**
	* 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_PrepareQuery_Metadata,

	/**
	* Error preparing an ImageQuery request
	*
	* Generated when the implementation encounters an error while preparing to send out
	* a software update query.
	*/
	kEvent_QueryPrepareFailed,

	/**
	* ImageQuery request has been sent
	*
	* Informational event to signal that a SofwareUpdate:ImageQuery message has been sent.
	*/
	kEvent_QuerySent,

	/**
	* Software update is available
	*
	* Generated when a SofwareUpdate:ImageQueryResponse is received in response to
	* a query containing information of the available update.
	*/
	kEvent_SoftwareUpdateAvailable,

	/**
	* 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_FetchPartialImageInfo,

	/**
	* 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
	* \c 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_PrepareImageStorage,

	/**
	* Image download has begun
	*
	* Informational event to signal the start of an image download transaction.
	*/
	kEvent_StartImageDownload,

	/**
	* 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.
	*/
	kEvent_StoreImageBlock,

	/**
	* 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_ComputeImageIntegrity,

	/**
	* 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_ResetPartialImageInfo,

	/**
	* 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_ReadyToInstall,

	/**
	* Begin image installation
	*
	* Requests the application to being the process of installing a downloaded firmware
	* image.
	*/
	kEvent_StartInstallImage,

	/**
	* 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_Finished,

	/**
	* Check default event handling behavior.
	*
	* Used to verify correct default event handling in the application.
	*
	* Applications must NOT handle this event.
	*/
	kEvent_DefaultCheck = 100,

	};

	/**
	* 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.
	*/
	enum ActionType
	{
	/**
	* 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.
	*/
	kAction_Ignore,

	/**
	* Start the download right away. A kEvent_FetchPartialImageInfo API event
	* callback will be generated right after.
	*/
	kAction_DownloadNow,

	/**
	* 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_DownloadLater,

	/**
	* 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_ApplicationManaged,
	};

	/**
	* Incoming parameters sent with events generated directly from this component
	*
	*/
	union InEventParam;

	/**
	* Outgoing parameters sent with events generated directly from this component
	*
	*/
	union OutEventParam;

	struct RetryParam
	{
	/**
	* Specifies the retry attempt number.
	* It is reset on a successful software update attempt.
	*/
	uint32_t NumRetries;
	};

	typedef void (EventCallback)(void apAppState, EventType aEvent, const InEventParam& aInParam, OutEventParam& aOutParam);
	typedef void (RetryPolicyCallback)(void aAppState, RetryParam& aRetryParam, uint32_t& aOutIntervalMsec);

	WEAVE_ERROR Abort(void);
	WEAVE_ERROR CheckNow(void);
	WEAVE_ERROR ImageInstallComplete(WEAVE_ERROR aError);
	WEAVE_ERROR PrepareImageStorageComplete(WEAVE_ERROR aError);
	WEAVE_ERROR SetEventCallback(void * const aAppState, const EventCallback aEventCallback);
	WEAVE_ERROR SetQueryIntervalWindow(uint32_t aMinWaitTimeMs, uint32_t aMaxWaitTimeMs);

	bool IsInProgress(void);

	void SetRetryPolicyCallback(const RetryPolicyCallback aRetryPolicyCallback);

	State GetState(void);

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

	private:
	// ===== Members for internal use by the following friends.

	// friend class SoftwareUpdateManagerImpl;
	template<class> friend class Internal::GenericPlatformManagerImpl;

	WEAVE_ERROR Init(void);

	protected:

	// Construction/destruction limited to subclasses.
	SoftwareUpdateManager() = default;
	~SoftwareUpdateManager() = default;

	// No copy, move or assignment.
	SoftwareUpdateManager(const SoftwareUpdateManager &) = delete;
	SoftwareUpdateManager(const SoftwareUpdateManager &&) = delete;
	SoftwareUpdateManager & operator=(const SoftwareUpdateManager &) = delete;
	};

	/**
	* Returns a reference to the public interface of the SoftwareUpdateManager singleton object.
	*
	* Weave application should use this to access features of the SoftwareUpdateManager object
	* that are common to all platforms.
	*/
	extern SoftwareUpdateManager & SoftwareUpdateMgr(void);

	/**
	* Returns the platform-specific implementation of the SoftwareUpdateManager singleton object.
	*
	* Weave applications can use this to gain access to features of the SoftwareUpdateManager
	* that are specific to the selected platform.
	*/
	extern SoftwareUpdateManagerImpl & SoftwareUpdateMgrImpl(void);

	} // namespace DeviceLayer
	} // namespace Weave
	} // namespace nl

	/* Include a header file containing the implementation of the SoftwareUpdateManager
	* object for the selected platform.
	*/
	#ifdef EXTERNAL_SOFTWAREUPDATEMANAGERIMPL_HEADER
	#include EXTERNAL_SOFTWAREUPDATEMANAGERIMPL_HEADER
	#else
	#define SOFTWAREUPDATEMANAGERIMPL_HEADER <Weave/DeviceLayer/WEAVE_DEVICE_LAYER_TARGET/SoftwareUpdateManagerImpl.h>
	#include SOFTWAREUPDATEMANAGERIMPL_HEADER
	#endif

	namespace nl {
	namespace Weave {
	namespace DeviceLayer {

	union SoftwareUpdateManager::InEventParam
	{
	void Clear(void) { memset(this, 0, sizeof(*this)); }

	SoftwareUpdateManager * Source;
	struct
	{
	TLVWriter * MetaDataWriter;
	} PrepareQuery_Metadata;

	struct
	{
	WEAVE_ERROR Error;
	Profiles::StatusReporting::StatusReport *StatusReport;
	} QueryPrepareFailed;

	struct
	{
	UpdatePriority Priority;
	UpdateCondition Condition;
	uint8_t IntegrityType;
	const char *URI;
	const char *Version;
	} SoftwareUpdateAvailable;

	struct
	{
	const char *URI;
	} FetchPartialImageInfo;

	struct
	{
	const char *URI;
	uint8_t IntegrityType;
	} PrepareImageStorage;

	struct
	{
	uint8_t *DataBlock;
	uint32_t DataBlockLen;
	} StoreImageBlock;

	struct
	{
	uint8_t IntegrityType;
	uint8_t *IntegrityValueBuf; // Pointer to the buffer for the app to copy Integrity Value into.
	uint8_t IntegrityValueBufLen; // Length of the provided buffer.
	} ComputeImageIntegrity;

	struct
	{
	WEAVE_ERROR Error;
	Profiles::StatusReporting::StatusReport *StatusReport;
	} Finished;
	};

	union SoftwareUpdateManager::OutEventParam
	{
	void Clear(void) { memset(this, 0, sizeof(*this)); }

	bool DefaultHandlerCalled;
	struct
	{
	const char *PackageSpecification;
	const char *DesiredLocale;
	WEAVE_ERROR Error;
	} PrepareQuery;

	struct
	{
	WEAVE_ERROR Error;
	} PrepareQuery_Metadata;

	struct
	{
	ActionType Action;
	} SoftwareUpdateAvailable;

	struct
	{
	uint64_t PartialImageLen;
	} FetchPartialImageInfo;

	struct
	{
	WEAVE_ERROR Error;
	} StoreImageBlock;

	struct
	{
	WEAVE_ERROR Error;
	} ComputeImageIntegrity;
	};

	inline WEAVE_ERROR SoftwareUpdateManager::Init(void)
	{
	return static_cast<ImplClass*>(this)->_Init();
	}

	inline WEAVE_ERROR SoftwareUpdateManager::CheckNow(void)
	{
	return static_cast<ImplClass*>(this)->_CheckNow();
	}

	inline WEAVE_ERROR SoftwareUpdateManager::ImageInstallComplete(WEAVE_ERROR aError)
	{
	return static_cast<ImplClass*>(this)->_ImageInstallComplete(aError);
	}

	inline WEAVE_ERROR SoftwareUpdateManager::PrepareImageStorageComplete(WEAVE_ERROR aError)
	{
	return static_cast<ImplClass*>(this)->_PrepareImageStorageComplete(aError);
	}

	inline SoftwareUpdateManager::State SoftwareUpdateManager::GetState(void)
	{
	return static_cast<ImplClass*>(this)->_GetState();
	}

	inline WEAVE_ERROR SoftwareUpdateManager::Abort(void)
	{
	return static_cast<ImplClass*>(this)->_Abort();
	}

	inline bool SoftwareUpdateManager::IsInProgress(void)
	{
	return static_cast<ImplClass*>(this)->_IsInProgress();
	}

	inline WEAVE_ERROR SoftwareUpdateManager::SetQueryIntervalWindow(uint32_t aMinRangeSecs, uint32_t aMaxRangeSecs)
	{
	return static_cast<ImplClass*>(this)->_SetQueryIntervalWindow(aMinRangeSecs, aMaxRangeSecs);
	}

	inline void SoftwareUpdateManager::SetRetryPolicyCallback(const RetryPolicyCallback aRetryPolicyCallback)
	{
	static_cast<ImplClass*>(this)->_SetRetryPolicyCallback(aRetryPolicyCallback);
	}

	inline WEAVE_ERROR SoftwareUpdateManager::SetEventCallback(void * const aAppState, const EventCallback aEventCallback)
	{
	return static_cast<ImplClass*>(this)->_SetEventCallback(aAppState, aEventCallback);
	}

	inline void SoftwareUpdateManager::DefaultEventHandler(void *apAppState, EventType aEvent,
	const InEventParam& aInParam,
	OutEventParam& aOutParam)
	{
	ImplClass::_DefaultEventHandler(apAppState, aEvent, aInParam, aOutParam);
	}

	} // namespace DeviceLayer
	} // namespace Weave
	} // namespace nl

	#endif // WEAVE_DEVICE_CONFIG_ENABLE_SOFTWARE_UPDATE_MANAGER
	#endif // SOFTWARE_UPDATE_MANAGER_H