Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2020-2021 Project CHIP Authors
4 : * All rights reserved.
5 : *
6 : * Licensed under the Apache License, Version 2.0 (the "License");
7 : * you may not use this file except in compliance with the License.
8 : * You may obtain a copy of the License at
9 : *
10 : * http://www.apache.org/licenses/LICENSE-2.0
11 : *
12 : * Unless required by applicable law or agreed to in writing, software
13 : * distributed under the License is distributed on an "AS IS" BASIS,
14 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 : * See the License for the specific language governing permissions and
16 : * limitations under the License.
17 : */
18 :
19 : #pragma once
20 :
21 : #include <app/CASEClientPool.h>
22 : #include <app/OperationalSessionSetup.h>
23 : #include <app/OperationalSessionSetupPool.h>
24 : #include <lib/address_resolve/AddressResolve.h>
25 : #include <lib/core/CHIPConfig.h>
26 : #include <lib/core/CHIPCore.h>
27 : #include <lib/support/Pool.h>
28 : #include <platform/CHIPDeviceLayer.h>
29 : #include <transport/SessionDelegate.h>
30 : #include <transport/SessionManager.h>
31 : #include <transport/SessionUpdateDelegate.h>
32 :
33 : namespace chip {
34 :
35 : struct CASESessionManagerConfig
36 : {
37 : CASEClientInitParams sessionInitParams;
38 : CASEClientPoolDelegate * clientPool = nullptr;
39 : OperationalSessionSetupPoolDelegate * sessionSetupPool = nullptr;
40 : };
41 :
42 : /**
43 : * This class provides the following
44 : * 1. Manage a pool of operational device proxy objects for peer nodes that have active message exchange with the local node.
45 : * 2. The pool contains atmost one device proxy object for a given peer node.
46 : * 3. API to lookup an existing proxy object, or allocate a new one by triggering session establishment with the peer node.
47 : * 4. During session establishment, trigger node ID resolution (if needed), and update the DNS-SD cache (if resolution is
48 : * successful)
49 : */
50 : class CASESessionManager : public OperationalSessionReleaseDelegate, public SessionUpdateDelegate
51 : {
52 : public:
53 68 : CASESessionManager() = default;
54 68 : virtual ~CASESessionManager()
55 68 : {
56 136 : if (mConfig.sessionInitParams.Validate() == CHIP_NO_ERROR)
57 : {
58 1 : mConfig.sessionInitParams.exchangeMgr->GetReliableMessageMgr()->RegisterSessionUpdateDelegate(nullptr);
59 : }
60 68 : }
61 :
62 : CHIP_ERROR Init(chip::System::Layer * systemLayer, const CASESessionManagerConfig & params);
63 : void Shutdown();
64 :
65 : /**
66 : * Find an existing session for the given node ID, or trigger a new session
67 : * request with optional DNS-SD fallback support.
68 : *
69 : * The caller can optionally provide `onConnection` and `onFailure` callback
70 : * objects. If provided, these will be used to inform the caller about
71 : * successful or failed connection establishment.
72 : *
73 : * If the connection is already established, the `onConnection` callback
74 : * will be immediately called, before FindOrEstablishSession returns.
75 : *
76 : * The `onFailure` callback may be called before the FindOrEstablishSession
77 : * call returns, for error cases that are detected synchronously.
78 : *
79 : * attemptCount can be set to a value greater than 1 to automatically make at least
80 : * attemptCount session establishment attempts until session setup is successful.
81 : */
82 : void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
83 : Callback::Callback<OnDeviceConnectionFailure> * onFailure,
84 : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
85 : uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
86 : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
87 : TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload,
88 : const Optional<AddressResolve::ResolveResult> & fallbackResolveResult = NullOptional);
89 :
90 : /**
91 : * Find an existing session for the given node ID or trigger a new session request.
92 : *
93 : * The caller can optionally provide `onConnection` and `onSetupFailure`
94 : * callback objects. If provided, these will be used to inform the caller about successful or
95 : * failed connection establishment.
96 : *
97 : * If the connection is already established, the `onConnection` callback will be immediately called,
98 : * before `FindOrEstablishSession` returns.
99 : *
100 : * The `onSetupFailure` callback may be called before the `FindOrEstablishSession`
101 : * call returns, for error cases that are detected synchronously.
102 : *
103 : * The `attemptCount` parameter can be set to a value greater than 1 to automatically make
104 : * at least attemptCount session establishment attempts until session setup is successful.
105 : *
106 : * @param peerId The node ID to find or establish a session with.
107 : * @param onConnection A callback to be called upon successful connection establishment.
108 : * @param onSetupFailure A callback to be called upon an extended device connection failure.
109 : * @param attemptCount The number of attempts to make at establishing a session. If set to a number larger than 1,
110 : * a session setup failure will lead to a retry, with at least attemptCount total attempts.
111 : * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
112 : * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
113 : */
114 : void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
115 : Callback::Callback<OperationalSessionSetup::OnSetupFailure> * onSetupFailure,
116 : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
117 : uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
118 : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
119 : TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);
120 :
121 : /**
122 : * Find an existing session for the given node ID or trigger a new session request.
123 : *
124 : * The caller can optionally provide `onConnection`
125 : * callback objects. If provided, these will be used to inform the caller about successful connection establishment.
126 : *
127 : * If the connection is already established, the `onConnection` callback will be immediately called,
128 : * before `FindOrEstablishSession` returns.
129 : *
130 : * The `attemptCount` parameter can be set to a value greater than 1 to automatically make
131 : * at least attemptCount session establishment attempts until session setup is successful.
132 : *
133 : * This function allows passing 'nullptr' for the error handler to compile, which is useful in scenarios where error
134 : * handling is not needed.
135 : *
136 : * @param peerId The node ID to find or establish a session with.
137 : * @param onConnection A callback to be called upon successful connection establishment.
138 : * @param attemptCount The number of attempts to make at establishing a session. If set to a number larger than 1,
139 : * a session setup failure will lead to a retry, with at least attemptCount total attempts.
140 : * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
141 : * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
142 : */
143 : void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection, std::nullptr_t,
144 : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
145 : uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
146 : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
147 : TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);
148 :
149 : /**
150 : * Find an existing session for the given node ID or trigger a new session request.
151 : *
152 : * The caller can optionally provide `onConnection`
153 : * callback objects. If provided, these will be used to inform the caller about successful connection establishment.
154 : *
155 : * If the connection is already established, the `onConnection` callback will be immediately called,
156 : * before `FindOrEstablishSession` returns.
157 : *
158 : * The `onFailure` callback may be called before the FindOrEstablishSession
159 : * call returns, for error cases that are detected synchronously.
160 : *
161 : * @note This API uses default values for automatic CASE retries, if enabled.
162 : *
163 : * @param peerId The node ID to find or establish a session with.
164 : * @param onConnection A callback to be called upon successful connection establishment.
165 : * @param onSetupFailure A callback to be called upon an extended device connection failure.
166 : * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
167 : */
168 : void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
169 : Callback::Callback<OnDeviceConnectionFailure> * onFailure,
170 : TransportPayloadCapability transportPayloadCapability);
171 :
172 : void ReleaseSession(const ScopedNodeId & peerId);
173 : void ReleaseSessionsForFabric(FabricIndex fabricIndex);
174 :
175 : void ReleaseAllSessions();
176 :
177 : /**
178 : * This API returns the address for the given node ID.
179 : * If the CASESessionManager is configured with a DNS-SD cache, the cache is looked up
180 : * for the node ID.
181 : * If the DNS-SD cache is not available, the CASESessionManager looks up the list for
182 : * an ongoing session with the peer node. If the session doesn't exist, the API will return
183 : * `CHIP_ERROR_NOT_CONNECTED` error.
184 : */
185 : CHIP_ERROR GetPeerAddress(const ScopedNodeId & peerId, Transport::PeerAddress & addr,
186 : TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);
187 :
188 : //////////// OperationalSessionReleaseDelegate Implementation ///////////////
189 : void ReleaseSession(OperationalSessionSetup * device) override;
190 :
191 : //////////// SessionUpdateDelegate Implementation ///////////////
192 : void UpdatePeerAddress(ScopedNodeId peerId) override;
193 :
194 : private:
195 : OperationalSessionSetup * FindExistingSessionSetup(const ScopedNodeId & peerId, bool forAddressUpdate = false) const;
196 :
197 : Optional<SessionHandle> FindExistingSession(
198 : const ScopedNodeId & peerId,
199 : const TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload) const;
200 :
201 : void FindOrEstablishSessionHelper(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
202 : Callback::Callback<OnDeviceConnectionFailure> * onFailure,
203 : Callback::Callback<OperationalSessionSetup::OnSetupFailure> * onSetupFailure,
204 : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
205 : uint8_t attemptCount, Callback::Callback<OnDeviceConnectionRetry> * onRetry,
206 : #endif
207 : TransportPayloadCapability transportPayloadCapability,
208 : const Optional<AddressResolve::ResolveResult> & fallbackResolveResult = NullOptional);
209 :
210 : CASESessionManagerConfig mConfig;
211 : };
212 :
213 : } // namespace chip
|
