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/AttributePathParams.h>
      20              : #include <app/ConcreteAttributePath.h>
      21              : #include <app/ConcreteClusterPath.h>
      22              : #include <app/ConcreteCommandPath.h>
      23              : #include <app/ConcreteEventPath.h>
      24              : #include <app/data-model-provider/MetadataTypes.h>
      25              : #include <app/data-model/List.h>
      26              : #include <clusters/Descriptor/Structs.h>
      27              : #include <lib/support/ReadOnlyBuffer.h>
      28              : #include <lib/support/Span.h>
      29              : 
      30              : namespace chip {
      31              : namespace app {
      32              : namespace DataModel {
      33              : 
      34              : /// Provides metadata information for a data model
      35              : ///
      36              : /// The data model can be viewed as a tree of endpoint/cluster/(attribute+commands+events)
      37              : /// where each element can be iterated through independently.
      38              : class ProviderMetadataTree
      39              : {
      40              : public:
      41          163 :     virtual ~ProviderMetadataTree() = default;
      42              : 
      43              :     using SemanticTag = Clusters::Descriptor::Structs::SemanticTagStruct::Type;
      44              : 
      45              :     virtual CHIP_ERROR Endpoints(ReadOnlyBufferBuilder<EndpointEntry> & builder) = 0;
      46              : 
      47              :     virtual CHIP_ERROR SemanticTags(EndpointId endpointId, ReadOnlyBufferBuilder<SemanticTag> & builder)          = 0;
      48              :     virtual CHIP_ERROR DeviceTypes(EndpointId endpointId, ReadOnlyBufferBuilder<DeviceTypeEntry> & builder)       = 0;
      49              :     virtual CHIP_ERROR ClientClusters(EndpointId endpointId, ReadOnlyBufferBuilder<ClusterId> & builder)          = 0;
      50              :     virtual CHIP_ERROR ServerClusters(EndpointId endpointId, ReadOnlyBufferBuilder<ServerClusterEntry> & builder) = 0;
      51              : #if CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID
      52              :     virtual CHIP_ERROR EndpointUniqueID(EndpointId endpointId, MutableCharSpan & EndpointUniqueId) = 0;
      53              : #endif
      54              : 
      55              :     /// Fetch event metadata for a specific event
      56              :     ///
      57              :     /// This metadata is used for event validation, specifically ACL at this time. Method is generally
      58              :     /// expected to return required access data for events.
      59              :     ///
      60              :     /// - Implementations MUST return valid event permission values for known events.
      61              :     /// - Implementations MAY choose to default to return a default kView when events are unknown,
      62              :     ///   in order to save on processing complexity and not deny event subscriptions
      63              :     ///   (even if specific events may never be generated).
      64              :     ///
      65              :     /// No explicit CHIP_ERROR values beyond CHIP_NO_ERROR (i.e. success) are defined. Returning failure
      66              :     /// from this method essentially means "This event is known as not supported by this provider" and
      67              :     /// the caller is not required to make any more differentiation beyond that, nor is the implementation
      68              :     /// required to return specific CHIP_ERROR values (like invalid endpoint/cluster/...)
      69              :     virtual CHIP_ERROR EventInfo(const ConcreteEventPath & path, EventEntry & eventInfo) = 0;
      70              : 
      71              :     /// Attribute lists contain all attributes. This MUST include all global
      72              :     /// attributes (See SPEC 7.13 Global Elements / Global Attributes Table).
      73              :     /// In particular this MUST contain:
      74              :     ///    - AcceptedCommandList::Id
      75              :     ///    - AttributeList::Id
      76              :     ///    - ClusterRevision::Id
      77              :     ///    - FeatureMap::Id
      78              :     ///    - GeneratedCommandList::Id
      79              :     virtual CHIP_ERROR Attributes(const ConcreteClusterPath & path, ReadOnlyBufferBuilder<AttributeEntry> & builder)   = 0;
      80              :     virtual CHIP_ERROR GeneratedCommands(const ConcreteClusterPath & path, ReadOnlyBufferBuilder<CommandId> & builder) = 0;
      81              :     virtual CHIP_ERROR AcceptedCommands(const ConcreteClusterPath & path,
      82              :                                         ReadOnlyBufferBuilder<AcceptedCommandEntry> & builder)                         = 0;
      83              : 
      84              :     /// Workaround function to report attribute change.
      85              :     ///
      86              :     /// When this is invoked, the caller is expected to increment the cluster data version, and the attribute path
      87              :     /// should be marked as `dirty` by the data model provider listener so that the reporter can notify the subscriber
      88              :     /// of attribute changes.
      89              :     /// This function should be invoked when attribute managed by attribute access interface is modified but not
      90              :     /// through an actual Write interaction.
      91              :     /// For example, if the LastNetworkingStatus attribute changes because the NetworkCommissioning driver detects a
      92              :     /// network connection status change and calls SetLastNetworkingStatusValue(). The data model provider can recognize
      93              :     /// this change by invoking this function at the point of change.
      94              :     ///
      95              :     /// This is a workaround function as we cannot notify the attribute change to the data model provider. The provider
      96              :     /// should own its data and versions.
      97              :     ///
      98              :     /// TODO: We should remove this function when the AttributeAccessInterface/CommandHandlerInterface is able to report
      99              :     /// the attribute changes.
     100              :     virtual void Temporary_ReportAttributeChanged(const AttributePathParams & path) = 0;
     101              : 
     102              :     // "convenience" functions that just return the data and ignore the error
     103              :     // This returns the `ReadOnlyBufferBuilder<..>::TakeBuffer` from their equivalent fuctions as-is,
     104              :     // even after an error (e.g. not found would return empty data).
     105              :     //
     106              :     // Usage of these indicates no error handling (not even logging) and code should
     107              :     // consider handling errors instead.
     108              :     ReadOnlyBuffer<EndpointEntry> EndpointsIgnoreError();
     109              :     ReadOnlyBuffer<ServerClusterEntry> ServerClustersIgnoreError(EndpointId endpointId);
     110              :     ReadOnlyBuffer<AttributeEntry> AttributesIgnoreError(const ConcreteClusterPath & path);
     111              : };
     112              : 
     113              : } // namespace DataModel
     114              : } // namespace app
     115              : } // namespace chip