Introduce header files for the OTA Requestor API declarations (#11605)

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 <[email protected]>

src/app/clusters/ota-requestor/ota-downloader.h

@@ -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;
+};

src/app/clusters/ota-requestor/ota-image-processor.h

@@ -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;
+};

src/app/clusters/ota-requestor/ota-requestor-driver.h

@@ -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;
+};

src/app/clusters/ota-requestor/ota-requestor-interface.h

@@ -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);
+};

src/app/clusters/ota-requestor/ota-requestor.h

@@ -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;
+};