Skip to content

Commit

Permalink
Introduce header files for the OTA Requestor API declarations (#11605)
Browse files Browse the repository at this point in the history
Problem
Need to start introducing APIs for the OTA Requestor refactoring

Change overview
Introduce ota-downloader.h, ota-image-processor.h, ota-requestor-driver.h, ota-requestor.h and ota-requestor-interface.h containing OTA Requestor API declarations.

Testing
No executable code changed. No testing beyond compilation and CI.

* Introduce ota-requestor.h containing Requestor API declarations

* Split OTA Requestor class declarations into multiple headers

* Restyled by whitespace

* Restyled by clang-format

* Clean up comments and function names

* Misc API format changes based on PR comments

* Restyled by clang-format

* Rename some classes and methods

* Rename a method

* Renaming avd vairious formatting changes

* Restyled by clang-format

* Add an API declaration

Co-authored-by: Restyled.io <commits@restyled.io>
  • Loading branch information
2 people authored and pull[bot] committed Jan 4, 2022
1 parent 85f0f0d commit c844531
Show file tree
Hide file tree
Showing 5 changed files with 238 additions and 0 deletions.
60 changes: 60 additions & 0 deletions src/app/clusters/ota-requestor/ota-downloader.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
/*
*
* Copyright (c) 2021 Project CHIP Authors
* 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.
*/

/* This file contains the declarations for the OTADownloader class which
* abstracts the image download functionality from the particular protocol
* used for it.
* Applications and platforms implementing the OTA Requestor functionality
* must include this file
*/

#include "ota-image-processor.h"

#pragma once

// A class that abstracts the image download functionality from the particular
// protocol used for that (BDX or possibly HTTPS)
class OTADownloader
{
public:
// API declarations start

// Application calls this method to direct OTADownloader to begin the download
void virtual BeginDownload();

// Platform calls this method upon the completion of PrepareDownload() processing
void virtual OnPreparedForDownload();

// Action parameter type for the OnBlockProcessed()
enum BlockActionType
{
kGetNext,
kEnd
};

// Platform calls this method upon the completion of ProcessBlock() processing
void virtual OnBlockProcessed(BlockActionType action);

// A setter for the delegate class pointer
void SetImageProcessorDelegate(OTAImageProcessorDriver * delegate);

// API declarations end

private:
OTAImageProcessorDriver * mImageProcessorDelegate;
};
47 changes: 47 additions & 0 deletions src/app/clusters/ota-requestor/ota-image-processor.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
/*
*
* Copyright (c) 2021 Project CHIP Authors
* 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.
*/

/* This file contains the declarations for OTAImageProcessor, a platform-agnostic
* interface for processing downloaded chunks of OTA image data.
* Each platform should provide an implementation of this interface.
*/

#pragma once

// This is a platform-agnostic interface for processing downloaded
// chunks of OTA image data (data could be raw image data meant for flash or
// metadata). Each platform should provide an implementation of this
// interface.
class OTAImageProcessorDriver
{
public:
// Open file, find block of space in persistent memory, or allocate a buffer, etc.
virtual CHIP_ERROR PrepareDownload() = 0;

// Must not be a blocking call to support cases that require IO to elements such as // external peripherals/radios
virtual CHIP_ERROR ProcessBlock(ByteSpan & data) = 0;

// Close file, close persistent storage, etc
virtual CHIP_ERROR Finalize() = 0;

virtual chip::Optional<uint8_t> PercentComplete() = 0;

// Clean up the download which could mean erasing everything that was written,
// releasing buffers, etc.
virtual CHIP_ERROR Abort() = 0;
};
39 changes: 39 additions & 0 deletions src/app/clusters/ota-requestor/ota-requestor-driver.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/*
*
* Copyright (c) 2021 Project CHIP Authors
* 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.
*/

/* This file contains the declaration for the OTARequestorDriver class, an interface
* that abstracts the OTA-related business logic out of the Requestor functionality in
* the Matter SDK. Applications implementing the OTA Requestor functionality must include
* this file.
*/

#pragma once

// Interface class to abstract the OTA-related business logic. Each application
// must implement this interface. All calls must be non-blocking unless stated otherwise
class OTARequestorDriver
{
public:
// A call into the application logic to give it a chance to allow or stop the Requestor
// from proceeding with actual image download. Returning TRUE will allow the download
// to proceed, returning FALSE will abort the download process.
virtual bool CheckImageDownloadAllowed() = 0;

// Notify the application that the download is complete and the image can be applied
virtual void ImageDownloadComplete() = 0;
};
43 changes: 43 additions & 0 deletions src/app/clusters/ota-requestor/ota-requestor-interface.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
/*
*
* Copyright (c) 2021 Project CHIP Authors
* 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.
*/

/* This file contains the declaration for the OTA Requestor interface.
* Any implementation of the OTA Requestor (e.g. the OTARequestor class) must implement
* this interface.
*/

#pragma once

// Interface class to connect the OTA Software Update Requestor cluster command processing
// with the core OTA Requestor logic. The OTARequestor class implements this interface
class OTARequestorInterface
{
public:
// Handler for the AnnounceOTAProvider command
virtual bool HandleAnnounceOTAProvider(
chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
const chip::app::Clusters::OtaSoftwareUpdateRequestor::Commands::AnnounceOtaProvider::DecodableType & commandData ch) = 0;

// Handler for the QueryImageResponse command
virtual bool HandleQueryImageResponse(void * context, uint8_t status, uint32_t delayedActionTime, CharSpan imageURI,
uint32_t softwareVersion, CharSpan softwareVersionString, ByteSpan updateToken,
bool userConsentNeeded, ByteSpan metadataForRequester) = 0;

// Handler for the ApplyUpdateResponse command
virtual bool HandleApplyUpdateResponse(ApplyUpdateResponse::DecodableType);
};
49 changes: 49 additions & 0 deletions src/app/clusters/ota-requestor/ota-requestor.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
/*
*
* Copyright (c) 2021 Project CHIP Authors
* 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.
*/

/* This file contains the declarations for the Matter OTA Requestor implementation and API.
* Applications implementing the OTA Requestor functionality must include this file.
*/

#include "ota-requestor-driver.h"
#include "ota-requestor-interface.h"

#pragma once

// This class implements all of the core logic of the OTA Requestor
class OTARequestor : public OTARequestorInterface
{
public:
// Application interface declarations start

// Application directs the Requestor to start the Image Query process
// and download the new image if available
void TriggerImmediateQuery();

// Application directs the Requestor to abort any processing related to
// the image update
void AbortImageUpdate();

// A setter for the delegate class pointer
void SetOtaRequestorDriver(OTARequestorDriver * driver);

// Application interface declarations end

private:
OTARequestorDriver * mOtaRequestorDriver;
};

0 comments on commit c844531

Please sign in to comment.