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/MetadataTypes.h>
      25              : #include <app/data-model/List.h>
      26              : #include <lib/support/ReadOnlyBuffer.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              : class ProviderMetadataTree
      38              : {
      39              : public:
      40          161 :     virtual ~ProviderMetadataTree() = default;
      41              : 
      42              :     using SemanticTag = Clusters::Descriptor::Structs::SemanticTagStruct::Type;
      43              : 
      44              :     virtual CHIP_ERROR Endpoints(ReadOnlyBufferBuilder<EndpointEntry> & builder) = 0;
      45              : 
      46              :     virtual CHIP_ERROR SemanticTags(EndpointId endpointId, ReadOnlyBufferBuilder<SemanticTag> & builder)          = 0;
      47              :     virtual CHIP_ERROR DeviceTypes(EndpointId endpointId, ReadOnlyBufferBuilder<DeviceTypeEntry> & builder)       = 0;
      48              :     virtual CHIP_ERROR ClientClusters(EndpointId endpointId, ReadOnlyBufferBuilder<ClusterId> & builder)          = 0;
      49              :     virtual CHIP_ERROR ServerClusters(EndpointId endpointId, ReadOnlyBufferBuilder<ServerClusterEntry> & builder) = 0;
      50              : #if CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID
      51              :     virtual CHIP_ERROR EndpointUniqueID(EndpointId endpointId, MutableCharSpan & EndpointUniqueId) = 0;
      52              : #endif
      53              : 
      54              :     /// Attribute lists contain all attributes. This MUST include all global
      55              :     /// attributes (See SPEC 7.13 Global Elements / Global Attributes Table).
      56              :     /// In particular this MUST contain:
      57              :     ///    - AcceptedCommandList::Id
      58              :     ///    - AttributeList::Id
      59              :     ///    - ClusterRevision::Id
      60              :     ///    - FeatureMap::Id
      61              :     ///    - GeneratedCommandList::Id
      62              :     virtual CHIP_ERROR Attributes(const ConcreteClusterPath & path, ReadOnlyBufferBuilder<AttributeEntry> & builder)   = 0;
      63              :     virtual CHIP_ERROR GeneratedCommands(const ConcreteClusterPath & path, ReadOnlyBufferBuilder<CommandId> & builder) = 0;
      64              :     virtual CHIP_ERROR AcceptedCommands(const ConcreteClusterPath & path,
      65              :                                         ReadOnlyBufferBuilder<AcceptedCommandEntry> & builder)                         = 0;
      66              : 
      67              :     /// Workaround function to report attribute change.
      68              :     ///
      69              :     /// When this is invoked, the caller is expected to increment the cluster data version, and the attribute path
      70              :     /// should be marked as `dirty` by the data model provider listener so that the reporter can notify the subscriber
      71              :     /// of attribute changes.
      72              :     /// This function should be invoked when attribute managed by attribute access interface is modified but not
      73              :     /// through an actual Write interaction.
      74              :     /// For example, if the LastNetworkingStatus attribute changes because the NetworkCommissioning driver detects a
      75              :     /// network connection status change and calls SetLastNetworkingStatusValue(). The data model provider can recognize
      76              :     /// this change by invoking this function at the point of change.
      77              :     ///
      78              :     /// This is a workaround function as we cannot notify the attribute change to the data model provider. The provider
      79              :     /// should own its data and versions.
      80              :     ///
      81              :     /// TODO: We should remove this function when the AttributeAccessInterface/CommandHandlerInterface is able to report
      82              :     /// the attribute changes.
      83              :     virtual void Temporary_ReportAttributeChanged(const AttributePathParams & path) = 0;
      84              : 
      85              :     // "convenience" functions that just return the data and ignore the error
      86              :     // This returns the `ReadOnlyBufferBuilder<..>::TakeBuffer` from their equivalent fuctions as-is,
      87              :     // even after an error (e.g. not found would return empty data).
      88              :     //
      89              :     // Usage of these indicates no error handling (not even logging) and code should
      90              :     // consider handling errors instead.
      91              :     ReadOnlyBuffer<EndpointEntry> EndpointsIgnoreError();
      92              :     ReadOnlyBuffer<ServerClusterEntry> ServerClustersIgnoreError(EndpointId endpointId);
      93              :     ReadOnlyBuffer<AttributeEntry> AttributesIgnoreError(const ConcreteClusterPath & path);
      94              : };
      95              : 
      96              : } // namespace DataModel
      97              : } // namespace app
      98              : } // namespace chip