Line data    Source code

       1              : /*
       2              :  *    Copyright (c) 2025 Project CHIP Authors
       3              :  *    All rights reserved.
       4              :  *
       5              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6              :  *    you may not use this file except in compliance with the License.
       7              :  *    You may obtain a copy of the License at
       8              :  *
       9              :  *        http://www.apache.org/licenses/LICENSE-2.0
      10              :  *
      11              :  *    Unless required by applicable law or agreed to in writing, software
      12              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14              :  *    See the License for the specific language governing permissions and
      15              :  *    limitations under the License.
      16              :  */
      17              : #pragma once
      18              : 
      19              : #include <app/server-cluster/ServerClusterInterface.h>
      20              : #include <optional>
      21              : 
      22              : namespace chip {
      23              : namespace app {
      24              : 
      25              : /// Provides an implementation of most methods for a `ServerClusterInterface`
      26              : /// to make it easier to implement spec-compliant classes.
      27              : ///
      28              : /// In particular it does:
      29              : ///   - maintains a data version and provides `IncreaseDataVersion`. Ensures this
      30              : ///     version is spec-compliant initialized (with a random value)
      31              : ///   - Provides default implementations for most virtual methods EXCEPT:
      32              : ///       - ReadAttribute (since that one needs to handle featuremap and revision)
      33              : ///       - GetClusterId (since every implementation is for different clusters)
      34              : ///
      35              : ///
      36              : class DefaultServerCluster : public ServerClusterInterface
      37              : {
      38              : public:
      39              :     DefaultServerCluster();
      40              :     ~DefaultServerCluster() override = default;
      41              : 
      42              :     //////////////////////////// ServerClusterInterface implementation ////////////////////////////////////////
      43              : 
      44              :     /// Startup allows only a single initialization per cluster and will
      45              :     /// fail with CHIP_ERROR_ALREADY_INITIALIZED if the object has already
      46              :     /// been initialized.
      47              :     ///
      48              :     /// Call Shutdown to de-initialize the object.
      49              :     CHIP_ERROR Startup(ServerClusterContext & context) override;
      50              :     void Shutdown() override;
      51              : 
      52            6 :     [[nodiscard]] DataVersion GetDataVersion() const override { return mDataVersion; }
      53              :     [[nodiscard]] BitFlags<DataModel::ClusterQualityFlags> GetClusterFlags() const override;
      54              : 
      55              :     /// Default implementation errors out with an unsupported write on every attribute.
      56              :     DataModel::ActionReturnStatus WriteAttribute(const DataModel::WriteAttributeRequest & request,
      57              :                                                  AttributeValueDecoder & decoder) override;
      58              : 
      59              :     /// Must only be implemented if support for any non-global attributes
      60              :     /// is required.
      61              :     ///
      62              :     /// Default implementation just returns the global attributes required by the API contract.
      63              :     CHIP_ERROR Attributes(const ConcreteClusterPath & path, DataModel::ListBuilder<DataModel::AttributeEntry> & builder) override;
      64              : 
      65              :     ///////////////////////////////////// Command Support /////////////////////////////////////////////////////////
      66              : 
      67              :     /// Must only be implemented if commands are supported by the cluster
      68              :     ///
      69              :     /// Default implementation errors out with an UnsupportedCommand error.
      70              :     std::optional<DataModel::ActionReturnStatus> InvokeCommand(const DataModel::InvokeRequest & request,
      71              :                                                                chip::TLV::TLVReader & input_arguments,
      72              :                                                                CommandHandler * handler) override;
      73              : 
      74              :     /// Must only be implemented if commands are supported by the cluster
      75              :     ///
      76              :     /// Default implementation is a NOOP (no list items generated)
      77              :     CHIP_ERROR AcceptedCommands(const ConcreteClusterPath & path,
      78              :                                 DataModel::ListBuilder<DataModel::AcceptedCommandEntry> & builder) override;
      79              : 
      80              :     /// Must only be implemented if commands that return values are supported by the cluster.
      81              :     ///
      82              :     /// Default implementation is a NOOP (no list items generated)
      83              :     CHIP_ERROR GeneratedCommands(const ConcreteClusterPath & path, DataModel::ListBuilder<CommandId> & builder) override;
      84              : 
      85              :     /// Returns all global attributes that the spec defines in `7.13 Global Elements / Table 93: Global Attributes`
      86              :     static Span<const DataModel::AttributeEntry> GlobalAttributes();
      87              : 
      88              : protected:
      89              :     ServerClusterContext * mContext = nullptr;
      90              : 
      91            3 :     void IncreaseDataVersion() { mDataVersion++; }
      92              : 
      93              :     /// Marks that a specific attribute has changed value
      94              :     ///
      95              :     /// This increases cluster data version and if a cluster context is available it will
      96              :     /// notify that the attribute has changed.
      97              :     void NotifyAttributeChanged(AttributeId attributeId);
      98              : 
      99              : private:
     100              :     DataVersion mDataVersion; // will be random-initialized as per spec
     101              : };
     102              : 
     103              : } // namespace app
     104              : } // namespace chip