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