Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2023 Project CHIP Authors
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 <access/SubjectDescriptor.h>
20 : #include <app/icd/server/ICDServerConfig.h>
21 : #include <lib/core/CHIPError.h>
22 : #include <lib/core/Optional.h>
23 : #include <lib/support/BitFlags.h>
24 :
25 : namespace chip {
26 : namespace app {
27 :
28 : /**
29 : * The ICDManager implements the ICDListener functions and is always subscribed to the ICDNotifier
30 : * This allows other Matter modules to inform the ICDManager that it needs to go and may have to stay in Active Mode,
31 : * outside of its standard ActiveModeDuration and IdleModeDuration, without being tightly coupled the application data model
32 : *
33 : * This implementation also allows other modules to implement an ICDListener and subscribe to ICDNotifier
34 : * to couple behaviours with the ICD cycles. In such cases, ICD_MAX_NOTIFICATION_SUBSCRIBERS need to be adjusted
35 : */
36 :
37 : static_assert(ICD_MAX_NOTIFICATION_SUBSCRIBERS > 0, "At least 1 Subscriber is required for the ICD Manager");
38 :
39 : class ICDListener
40 : {
41 : public:
42 : enum class KeepActiveFlagsValues : uint8_t
43 : {
44 : kCommissioningWindowOpen = 0x01,
45 : kFailSafeArmed = 0x02,
46 : kExchangeContextOpen = 0x04,
47 : kCheckInInProgress = 0x08,
48 : kTestEventTriggerActiveMode = 0x10,
49 : kInvalidFlag = 0x20, // Move up when adding more flags
50 : };
51 :
52 : enum class ICDManagementEvents : uint8_t
53 : {
54 : kTableUpdated = 0x01,
55 : };
56 :
57 : using KeepActiveFlags = BitFlags<KeepActiveFlagsValues>;
58 : using KeepActiveFlag = KeepActiveFlagsValues;
59 :
60 10 : virtual ~ICDListener() {}
61 :
62 : /**
63 : * @brief This function is called for all subscribers of the ICDNotifier when it calls NotifyNetworkActivityNotification.
64 : * It notifies the subscriber that a NetworkActivity occurred. For example, a message sent or received.
65 : */
66 : virtual void OnNetworkActivity() = 0;
67 :
68 : /**
69 : * @brief This function is called for all subscribers of the ICDNotifier when it calls NotifyActiveRequestNotification.
70 : * It informs the subscriber that there is a need to place and keep the ICD in its Active Mode.
71 : *
72 : * @param request : Identity the request source
73 : */
74 : virtual void OnKeepActiveRequest(KeepActiveFlags request) = 0;
75 :
76 : #if CHIP_CONFIG_ENABLE_ICD_DSLS
77 : /**
78 : * @brief This function is called for all subscribers of the ICDNotifier when it calls NotifySITModeRequestNotification.
79 : * It informs the subscriber that the ICD must be kept in SIT mode.
80 : */
81 : virtual void OnSITModeRequest() = 0;
82 :
83 : /**
84 : * @brief This function is called for all subscribers of the ICDNotifier when it calls NotifySITModeRequestWithdrawal.
85 : * It informs the subscriber that a previous request no longer needs ICD to be kept in SIT mode.
86 : */
87 : virtual void OnSITModeRequestWithdrawal() = 0;
88 : #endif // CHIP_CONFIG_ENABLE_ICD_DSLS
89 :
90 : /**
91 : * @brief This function is called for all subscribers of the ICDNotifier when it calls NotifyActiveRequestWithdrawal.
92 : * It informs the subscriber that a previous request no longer needs ICD to maintain its Active Mode.
93 : *
94 : * @param request : The request source
95 : */
96 : virtual void OnActiveRequestWithdrawal(KeepActiveFlags request) = 0;
97 :
98 : /**
99 : * @brief This function is called for all subscribers of the ICDNotifier when it calls NotifyICDManagementEvent.
100 : * It informs the subscriber that an ICD Management action has happened and needs to be processed
101 : *
102 : * @param event : The event type
103 : */
104 : virtual void OnICDManagementServerEvent(ICDManagementEvents event) = 0;
105 :
106 : /**
107 : * @brief This function is called for all subscribers of the ICDNoitifier when it calls NotifySubscriptionReport.
108 : * It informs the subscriber that a subscription report data is being sent.
109 : */
110 : virtual void OnSubscriptionReport() = 0;
111 :
112 : #if CHIP_CONFIG_ENABLE_ICD_SERVER && CHIP_CONFIG_ENABLE_ICD_CIP && CHIP_CONFIG_ENABLE_ICD_CHECK_IN_ON_REPORT_TIMEOUT
113 : /**
114 : * @brief This function is called for all subscribers of the ICDNotifier when it calls NotifySendCheckIn.
115 : * It informs the subscriber that a Check-In message needs to be sent for the provided subject.
116 : *
117 : * @param subject : The subject descriptor for which the Check-In message needs to be sent.
118 : * If not provided, Check-In messages should be sent for all subjects that require it.
119 : */
120 : virtual void OnSendCheckIn(Optional<Access::SubjectDescriptor> specificSubject) = 0;
121 : #endif // CHIP_CONFIG_ENABLE_ICD_SERVER && CHIP_CONFIG_ENABLE_ICD_CIP && CHIP_CONFIG_ENABLE_ICD_CHECK_IN_ON_REPORT_TIMEOUT
122 : };
123 :
124 : class ICDNotifier
125 : {
126 : public:
127 : ~ICDNotifier();
128 : CHIP_ERROR Subscribe(ICDListener * subscriber);
129 : void Unsubscribe(ICDListener * subscriber);
130 :
131 : /**
132 : * The following Broacast* methods triggers all the registered ICDSubscribers related callback
133 : * For thread-safety reason (mostly of the ICDManager, which is a full time subscriber),
134 : * Those functions require to be called from the Chip Task Context, or by holding the chip stack lock.
135 : */
136 : void NotifyNetworkActivityNotification();
137 : void NotifyActiveRequestNotification(ICDListener::KeepActiveFlags request);
138 : void NotifyActiveRequestWithdrawal(ICDListener::KeepActiveFlags request);
139 : #if CHIP_CONFIG_ENABLE_ICD_DSLS
140 : void NotifySITModeRequestNotification();
141 : void NotifySITModeRequestWithdrawal();
142 : #endif // CHIP_CONFIG_ENABLE_ICD_DSLS
143 : void NotifyICDManagementEvent(ICDListener::ICDManagementEvents event);
144 : void NotifySubscriptionReport();
145 :
146 : #if CHIP_CONFIG_ENABLE_ICD_SERVER && CHIP_CONFIG_ENABLE_ICD_CIP && CHIP_CONFIG_ENABLE_ICD_CHECK_IN_ON_REPORT_TIMEOUT
147 : void NotifySendCheckIn(Optional<Access::SubjectDescriptor> specificSubject);
148 : #endif // CHIP_CONFIG_ENABLE_ICD_SERVER && CHIP_CONFIG_ENABLE_ICD_CIP && CHIP_CONFIG_ENABLE_ICD_CHECK_IN_ON_REPORT_TIMEOUT
149 :
150 : inline void BroadcastActiveRequest(ICDListener::KeepActiveFlags request, bool notify)
151 : {
152 : (notify) ? NotifyActiveRequestNotification(request) : NotifyActiveRequestWithdrawal(request);
153 : }
154 :
155 26 : static ICDNotifier & GetInstance() { return sICDNotifier; }
156 :
157 : private:
158 : static ICDNotifier sICDNotifier;
159 : ICDListener * mSubscribers[ICD_MAX_NOTIFICATION_SUBSCRIBERS] = {};
160 : };
161 :
162 : } // namespace app
163 : } // namespace chip
|
