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
|