/src/connectedhomeip/src/app/CASESessionManager.h

Source
/*
 *
 *    Copyright (c) 2020-2021 Project CHIP Authors
 *    All rights reserved.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

#pragma once

#include <app/CASEClientPool.h>
#include <app/OperationalSessionSetup.h>
#include <app/OperationalSessionSetupPool.h>
#include <lib/address_resolve/AddressResolve.h>
#include <lib/core/CHIPConfig.h>
#include <lib/core/CHIPCore.h>
#include <lib/support/Pool.h>
#include <platform/CHIPDeviceLayer.h>
#include <transport/SessionDelegate.h>
#include <transport/SessionManager.h>
#include <transport/SessionUpdateDelegate.h>

namespace chip {

struct CASESessionManagerConfig
{
    CASEClientInitParams sessionInitParams;
    CASEClientPoolDelegate * clientPool                    = nullptr;
    OperationalSessionSetupPoolDelegate * sessionSetupPool = nullptr;
};

/**
 * This class provides the following
 * 1. Manage a pool of operational device proxy objects for peer nodes that have active message exchange with the local node.
 * 2. The pool contains atmost one device proxy object for a given peer node.
 * 3. API to lookup an existing proxy object, or allocate a new one by triggering session establishment with the peer node.
 * 4. During session establishment, trigger node ID resolution (if needed), and update the DNS-SD cache (if resolution is
 * successful)
 */
class CASESessionManager : public OperationalSessionReleaseDelegate, public SessionUpdateDelegate
{
public:
    CASESessionManager() = default;
    virtual ~CASESessionManager()
    {
        if (mConfig.sessionInitParams.Validate() == CHIP_NO_ERROR)
        {
            mConfig.sessionInitParams.exchangeMgr->GetReliableMessageMgr()->RegisterSessionUpdateDelegate(nullptr);
        }
    }

    CHIP_ERROR Init(chip::System::Layer * systemLayer, const CASESessionManagerConfig & params);
    void Shutdown();

    /**
     * Find an existing session for the given node ID, or trigger a new session
     * request with optional DNS-SD fallback support.
     *
     * The caller can optionally provide `onConnection` and `onFailure` callback
     * objects. If provided, these will be used to inform the caller about
     * successful or failed connection establishment.
     *
     * If the connection is already established, the `onConnection` callback
     * will be immediately called, before FindOrEstablishSession returns.
     *
     * The `onFailure` callback may be called before the FindOrEstablishSession
     * call returns, for error cases that are detected synchronously.
     *
     * attemptCount can be set to a value greater than 1 to automatically make at least
     * attemptCount session establishment attempts until session setup is successful.
     */
    void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
                                Callback::Callback<OnDeviceConnectionFailure> * onFailure,
#if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
                                uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
#endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
                                TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload,
                                const Optional<AddressResolve::ResolveResult> & fallbackResolveResult = NullOptional);

    /**
     * Find an existing session for the given node ID or trigger a new session request.
     *
     * The caller can optionally provide `onConnection` and `onSetupFailure`
     * callback objects. If provided, these will be used to inform the caller about successful or
     * failed connection establishment.
     *
     * If the connection is already established, the `onConnection` callback will be immediately called,
     * before `FindOrEstablishSession` returns.
     *
     * The `onSetupFailure` callback may be called before the `FindOrEstablishSession`
     * call returns, for error cases that are detected synchronously.
     *
     * The `attemptCount` parameter can be set to a value greater than 1 to automatically make
     * at least attemptCount session establishment attempts until session setup is successful.
     *
     * @param peerId The node ID to find or establish a session with.
     * @param onConnection A callback to be called upon successful connection establishment.
     * @param onSetupFailure A callback to be called upon an extended device connection failure.
     * @param attemptCount The number of attempts to make at establishing a session.  If set to a number larger than 1,
     *                     a session setup failure will lead to a retry, with at least attemptCount total attempts.
     * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
     * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
     */
    void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
                                Callback::Callback<OperationalSessionSetup::OnSetupFailure> * onSetupFailure,
#if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
                                uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
#endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
                                TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);

    /**
     * Find an existing session for the given node ID or trigger a new session request.
     *
     * The caller can optionally provide `onConnection`
     * callback objects. If provided, these will be used to inform the caller about successful connection establishment.
     *
     * If the connection is already established, the `onConnection` callback will be immediately called,
     * before `FindOrEstablishSession` returns.
     *
     * The `attemptCount` parameter can be set to a value greater than 1 to automatically make
     * at least attemptCount session establishment attempts until session setup is successful.
     *
     * This function allows passing 'nullptr' for the error handler to compile, which is useful in scenarios where error
     * handling is not needed.
     *
     * @param peerId The node ID to find or establish a session with.
     * @param onConnection A callback to be called upon successful connection establishment.
     * @param attemptCount The number of attempts to make at establishing a session.  If set to a number larger than 1,
     *                     a session setup failure will lead to a retry, with at least attemptCount total attempts.
     * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
     * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
     */
    void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection, std::nullptr_t,
#if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
                                uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
#endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
                                TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);

    /**
     * Find an existing session for the given node ID or trigger a new session request.
     *
     * The caller can optionally provide `onConnection`
     * callback objects. If provided, these will be used to inform the caller about successful connection establishment.
     *
     * If the connection is already established, the `onConnection` callback will be immediately called,
     * before `FindOrEstablishSession` returns.
     *
     * The `onFailure` callback may be called before the FindOrEstablishSession
     * call returns, for error cases that are detected synchronously.
     *
     * @note This API uses default values for automatic CASE retries, if enabled.
     *
     * @param peerId The node ID to find or establish a session with.
     * @param onConnection A callback to be called upon successful connection establishment.
     * @param onSetupFailure A callback to be called upon an extended device connection failure.
     * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
     */
    void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
                                Callback::Callback<OnDeviceConnectionFailure> * onFailure,
                                TransportPayloadCapability transportPayloadCapability);

    void ReleaseSession(const ScopedNodeId & peerId);
    void ReleaseSessionsForFabric(FabricIndex fabricIndex);

    void ReleaseAllSessions();

    /**
     * This API returns the address for the given node ID.
     * If the CASESessionManager is configured with a DNS-SD cache, the cache is looked up
     * for the node ID.
     * If the DNS-SD cache is not available, the CASESessionManager looks up the list for
     * an ongoing session with the peer node. If the session doesn't exist, the API will return
     * `CHIP_ERROR_NOT_CONNECTED` error.
     */
    CHIP_ERROR GetPeerAddress(const ScopedNodeId & peerId, Transport::PeerAddress & addr,
                              TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);

    //////////// OperationalSessionReleaseDelegate Implementation ///////////////
    void ReleaseSession(OperationalSessionSetup * device) override;

    //////////// SessionUpdateDelegate Implementation ///////////////
    void UpdatePeerAddress(ScopedNodeId peerId) override;

private:
    OperationalSessionSetup * FindExistingSessionSetup(const ScopedNodeId & peerId, bool forAddressUpdate = false) const;

    Optional<SessionHandle> FindExistingSession(
        const ScopedNodeId & peerId,
        const TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload) const;

    void FindOrEstablishSessionHelper(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
                                      Callback::Callback<OnDeviceConnectionFailure> * onFailure,
                                      Callback::Callback<OperationalSessionSetup::OnSetupFailure> * onSetupFailure,
#if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
                                      uint8_t attemptCount, Callback::Callback<OnDeviceConnectionRetry> * onRetry,
#endif
                                      TransportPayloadCapability transportPayloadCapability,
                                      const Optional<AddressResolve::ResolveResult> & fallbackResolveResult = NullOptional);

    CASESessionManagerConfig mConfig;
};

} // namespace chip

Coverage Report

Created: 2026-02-12 06:57

Line	Count	Source
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	2	CASESessionManager() = default;
54		virtual ~CASESessionManager()
55	0	{
56	0	if (mConfig.sessionInitParams.Validate() == CHIP_NO_ERROR)
57	0	{
58	0	mConfig.sessionInitParams.exchangeMgr->GetReliableMessageMgr()->RegisterSessionUpdateDelegate(nullptr);
59	0	}
60	0	}
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