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