Line data    Source code

       1              : /*
       2              :  *    Copyright (c) 2024 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-common/zap-generated/cluster-objects.h>
      20              : #include <app/AttributePathParams.h>
      21              : #include <app/ConcreteAttributePath.h>
      22              : #include <app/ConcreteClusterPath.h>
      23              : #include <app/ConcreteCommandPath.h>
      24              : #include <app/data-model-provider/MetadataList.h>
      25              : #include <app/data-model-provider/MetadataTypes.h>
      26              : #include <app/data-model/List.h>
      27              : #include <lib/support/Span.h>
      28              : 
      29              : namespace chip {
      30              : namespace app {
      31              : namespace DataModel {
      32              : 
      33              : /// Provides metadata information for a data model
      34              : ///
      35              : /// The data model can be viewed as a tree of endpoint/cluster/(attribute+commands+events)
      36              : /// where each element can be iterated through independently.
      37              : ///
      38              : /// Iteration rules:
      39              : ///   - Invalid paths will be returned when iteration ends (IDs will be kInvalid* and in particular
      40              : ///     mEndpointId will be kInvalidEndpointId). See `::kInvalid` constants for entries and
      41              : ///     can use ::IsValid() to determine if the entry is valid or not.
      42              : ///   - Global Attributes are NOT returned since they are implied
      43              : ///   - Any internal iteration errors are just logged (callers do not handle iteration CHIP_ERROR)
      44              : ///   - Iteration order is NOT guaranteed globally. Only the following is guaranteed:
      45              : ///     - Complete tree iteration (e.g. when iterating an endpoint, ALL clusters of that endpoint
      46              : ///       are returned, when iterating over a cluster, all attributes/commands are iterated over)
      47              : ///     - uniqueness and completeness (iterate over all possible distinct values as long as no
      48              : ///       internal structural changes occur)
      49              : class ProviderMetadataTree
      50              : {
      51              : public:
      52          153 :     virtual ~ProviderMetadataTree() = default;
      53              : 
      54              :     using SemanticTag = Clusters::Descriptor::Structs::SemanticTagStruct::Type;
      55              : 
      56              :     virtual CHIP_ERROR Endpoints(ListBuilder<EndpointEntry> & builder) = 0;
      57              : 
      58              :     virtual CHIP_ERROR SemanticTags(EndpointId endpointId, ListBuilder<SemanticTag> & builder)          = 0;
      59              :     virtual CHIP_ERROR DeviceTypes(EndpointId endpointId, ListBuilder<DeviceTypeEntry> & builder)       = 0;
      60              :     virtual CHIP_ERROR ClientClusters(EndpointId endpointId, ListBuilder<ClusterId> & builder)          = 0;
      61              :     virtual CHIP_ERROR ServerClusters(EndpointId endpointId, ListBuilder<ServerClusterEntry> & builder) = 0;
      62              : 
      63              :     /// Attribute lists contain all attributes. This MUST include all global
      64              :     /// attributes (See SPEC 7.13 Global Elements / Global Attributes Table).
      65              :     /// In particular this MUST contain:
      66              :     ///    - AcceptedCommandList::Id
      67              :     ///    - AttributeList::Id
      68              :     ///    - ClusterRevision::Id
      69              :     ///    - FeatureMap::Id
      70              :     ///    - GeneratedCommandList::Id
      71              :     virtual CHIP_ERROR Attributes(const ConcreteClusterPath & path, ListBuilder<AttributeEntry> & builder)             = 0;
      72              :     virtual CHIP_ERROR GeneratedCommands(const ConcreteClusterPath & path, ListBuilder<CommandId> & builder)           = 0;
      73              :     virtual CHIP_ERROR AcceptedCommands(const ConcreteClusterPath & path, ListBuilder<AcceptedCommandEntry> & builder) = 0;
      74              : 
      75              :     /// Workaround function to report attribute change.
      76              :     ///
      77              :     /// When this is invoked, the caller is expected to increment the cluster data version, and the attribute path
      78              :     /// should be marked as `dirty` by the data model provider listener so that the reporter can notify the subscriber
      79              :     /// of attribute changes.
      80              :     /// This function should be invoked when attribute managed by attribute access interface is modified but not
      81              :     /// through an actual Write interaction.
      82              :     /// For example, if the LastNetworkingStatus attribute changes because the NetworkCommissioning driver detects a
      83              :     /// network connection status change and calls SetLastNetworkingStatusValue(). The data model provider can recognize
      84              :     /// this change by invoking this function at the point of change.
      85              :     ///
      86              :     /// This is a workaround function as we cannot notify the attribute change to the data model provider. The provider
      87              :     /// should own its data and versions.
      88              :     ///
      89              :     /// TODO: We should remove this function when the AttributeAccessInterface/CommandHandlerInterface is able to report
      90              :     /// the attribute changes.
      91              :     virtual void Temporary_ReportAttributeChanged(const AttributePathParams & path) = 0;
      92              : 
      93              :     // "convenience" functions that just return the data and ignore the error
      94              :     // This returns the `ListBuilder<..>::TakeBuffer` from their equivalent fuctions as-is,
      95              :     // even after an error (e.g. not found would return empty data).
      96              :     //
      97              :     // Usage of these indicates no error handling (not even logging) and code should
      98              :     // consider handling errors instead.
      99              :     ReadOnlyBuffer<EndpointEntry> EndpointsIgnoreError();
     100              :     ReadOnlyBuffer<ServerClusterEntry> ServerClustersIgnoreError(EndpointId endpointId);
     101              :     ReadOnlyBuffer<AttributeEntry> AttributesIgnoreError(const ConcreteClusterPath & path);
     102              : };
     103              : 
     104              : } // namespace DataModel
     105              : } // namespace app
     106              : } // namespace chip