Skip to content

Commit 84117dd

Browse files
tehampsonbzbarsky-apple
tehampson
and
bzbarsky-apple
authored
Move CommandSender::Callback into CommandSenderLegacyCallback.h (project-chip#31370)
--------- Co-authored-by: Boris Zbarsky <bzbarsky@apple.com>
1 parent 166c4b5 commit 84117dd

File tree

2 files changed

+107
-71
lines changed

2 files changed

+107
-71
lines changed

‎src/app/CommandSender.h

+6-71
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@
2626

2727
#include <type_traits>
2828

29+
#include "CommandSenderLegacyCallback.h"
30+
2931
#include <app/CommandPathParams.h>
3032
#include <app/MessageDef/InvokeRequestMessage.h>
3133
#include <app/MessageDef/InvokeResponseMessage.h>
@@ -53,77 +55,6 @@ namespace app {
5355
class CommandSender final : public Messaging::ExchangeDelegate
5456
{
5557
public:
56-
// TODO(#30453) Reorder CommandSender::Callback and CommandSender::ExtendableCallback. To keep follow up
57-
// review simple, this was not done initially, and is expected to be completed within day of PR
58-
// introducing CommandSender::ExtendableCallback getting merged.
59-
/**
60-
* @brief Legacy callbacks for CommandSender
61-
*/
62-
class Callback
63-
{
64-
public:
65-
virtual ~Callback() = default;
66-
67-
/**
68-
* OnResponse will be called when a successful response from server has been received and processed.
69-
* Specifically:
70-
* - When a status code is received and it is IM::Success, aData will be nullptr.
71-
* - When a data response is received, aData will point to a valid TLVReader initialized to point at the struct container
72-
* that contains the data payload (callee will still need to open and process the container).
73-
*
74-
* The CommandSender object MUST continue to exist after this call is completed. The application shall wait until it
75-
* receives an OnDone call to destroy the object.
76-
*
77-
* @param[in] apCommandSender The command sender object that initiated the command transaction.
78-
* @param[in] aPath The command path field in invoke command response.
79-
* @param[in] aStatusIB It will always have a success status. If apData is null, it can be any success status,
80-
* including possibly a cluster-specific one. If apData is not null it aStatusIB will always
81-
* be a generic SUCCESS status with no-cluster specific information.
82-
* @param[in] apData The command data, will be nullptr if the server returns a StatusIB.
83-
*/
84-
virtual void OnResponse(CommandSender * apCommandSender, const ConcreteCommandPath & aPath, const StatusIB & aStatusIB,
85-
TLV::TLVReader * apData)
86-
{}
87-
88-
/**
89-
* OnError will be called when an error occurs *after* a successful call to SendCommandRequest(). The following
90-
* errors will be delivered through this call in the aError field:
91-
*
92-
* - CHIP_ERROR_TIMEOUT: A response was not received within the expected response timeout.
93-
* - CHIP_ERROR_*TLV*: A malformed, non-compliant response was received from the server.
94-
* - CHIP_ERROR encapsulating a StatusIB: If we got a non-path-specific or path-specific
95-
* status response from the server. In that case,
96-
* StatusIB::InitFromChipError can be used to extract the status.
97-
* - Note: a CommandSender using `CommandSender::Callback` only supports sending
98-
* a single InvokeRequest. As a result, only one path-specific error is expected
99-
* to ever be sent to the OnError callback.
100-
* - CHIP_ERROR*: All other cases.
101-
*
102-
* The CommandSender object MUST continue to exist after this call is completed. The application shall wait until it
103-
* receives an OnDone call to destroy and free the object.
104-
*
105-
* @param[in] apCommandSender The command sender object that initiated the command transaction.
106-
* @param[in] aError A system error code that conveys the overall error code.
107-
*/
108-
virtual void OnError(const CommandSender * apCommandSender, CHIP_ERROR aError) {}
109-
110-
/**
111-
* OnDone will be called when CommandSender has finished all work and it is safe to destroy and free the
112-
* allocated CommandSender object.
113-
*
114-
* This function will:
115-
* - Always be called exactly *once* for a given CommandSender instance.
116-
* - Be called even in error circumstances.
117-
* - Only be called after a successful call to SendCommandRequest returns, if SendCommandRequest is used.
118-
* - Always be called before a successful return from SendGroupCommandRequest, if SendGroupCommandRequest is used.
119-
*
120-
* This function must be implemented to destroy the CommandSender object.
121-
*
122-
* @param[in] apCommandSender The command sender object of the terminated invoke command transaction.
123-
*/
124-
virtual void OnDone(CommandSender * apCommandSender) = 0;
125-
};
126-
12758
// CommandSender::ExtendableCallback::OnResponse is public SDK API, so we cannot break
12859
// source compatibility for it. To allow for additional values to be added at a future
12960
// time without constantly changing the function's declaration parameter list, we are
@@ -229,6 +160,10 @@ class CommandSender final : public Messaging::ExchangeDelegate
229160
virtual void OnDone(CommandSender * apCommandSender) = 0;
230161
};
231162

163+
// `Callback` exists for legacy purposes. If you are developing a new callback implementation,
164+
// please use `ExtendableCallback`.
165+
using Callback = CommandSenderLegacyCallback;
166+
232167
// SetCommandSenderConfig is a public SDK API, so we cannot break source compatibility
233168
// for it. By having parameters to that API use this struct instead of individual
234169
// function arguments, we centralize required changes to one file when adding new

‎src/app/CommandSenderLegacyCallback.h

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
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+
18+
#pragma once
19+
20+
#include <app/ConcreteCommandPath.h>
21+
#include <app/MessageDef/StatusIB.h>
22+
#include <lib/core/TLV.h>
23+
24+
namespace chip {
25+
namespace app {
26+
27+
class CommandSender;
28+
29+
/**
30+
* @brief Legacy callbacks for CommandSender
31+
*
32+
* This class exists for legacy purposes. If you are developing a new callback implementation,
33+
* please use `CommandSender::ExtendableCallback`.
34+
*/
35+
class CommandSenderLegacyCallback
36+
{
37+
public:
38+
virtual ~CommandSenderLegacyCallback() = default;
39+
40+
/**
41+
* OnResponse will be called when a successful response from server has been received and processed.
42+
* Specifically:
43+
* - When a status code is received and it is IM::Success, aData will be nullptr.
44+
* - When a data response is received, aData will point to a valid TLVReader initialized to point at the struct container
45+
* that contains the data payload (callee will still need to open and process the container).
46+
*
47+
* The CommandSender object MUST continue to exist after this call is completed. The application shall wait until it
48+
* receives an OnDone call to destroy the object.
49+
*
50+
* @param[in] apCommandSender The command sender object that initiated the command transaction.
51+
* @param[in] aPath The command path field in invoke command response.
52+
* @param[in] aStatusIB It will always have a success status. If apData is null, it can be any success status,
53+
* including possibly a cluster-specific one. If apData is not null it aStatusIB will always
54+
* be a generic SUCCESS status with no-cluster specific information.
55+
* @param[in] apData The command data, will be nullptr if the server returns a StatusIB.
56+
*/
57+
virtual void OnResponse(CommandSender * apCommandSender, const ConcreteCommandPath & aPath, const StatusIB & aStatusIB,
58+
TLV::TLVReader * apData)
59+
{}
60+
61+
/**
62+
* OnError will be called when an error occurs *after* a successful call to SendCommandRequest(). The following
63+
* errors will be delivered through this call in the aError field:
64+
*
65+
* - CHIP_ERROR_TIMEOUT: A response was not received within the expected response timeout.
66+
* - CHIP_ERROR_*TLV*: A malformed, non-compliant response was received from the server.
67+
* - CHIP_ERROR encapsulating a StatusIB: If we got a non-path-specific or path-specific
68+
* status response from the server. In that case,
69+
* StatusIB::InitFromChipError can be used to extract the status.
70+
* - Note: a CommandSender using `CommandSender::Callback` only supports sending
71+
* a single InvokeRequest. As a result, only one path-specific error is expected
72+
* to ever be sent to the OnError callback.
73+
* - CHIP_ERROR*: All other cases.
74+
*
75+
* The CommandSender object MUST continue to exist after this call is completed. The application shall wait until it
76+
* receives an OnDone call to destroy and free the object.
77+
*
78+
* @param[in] apCommandSender The command sender object that initiated the command transaction.
79+
* @param[in] aError A system error code that conveys the overall error code.
80+
*/
81+
virtual void OnError(const CommandSender * apCommandSender, CHIP_ERROR aError) {}
82+
83+
/**
84+
* OnDone will be called when CommandSender has finished all work and it is safe to destroy and free the
85+
* allocated CommandSender object.
86+
*
87+
* This function will:
88+
* - Always be called exactly *once* for a given CommandSender instance.
89+
* - Be called even in error circumstances.
90+
* - Only be called after a successful call to SendCommandRequest returns, if SendCommandRequest is used.
91+
* - Always be called before a successful return from SendGroupCommandRequest, if SendGroupCommandRequest is used.
92+
*
93+
* This function must be implemented to destroy the CommandSender object.
94+
*
95+
* @param[in] apCommandSender The command sender object of the terminated invoke command transaction.
96+
*/
97+
virtual void OnDone(CommandSender * apCommandSender) = 0;
98+
};
99+
100+
} // namespace app
101+
} // namespace chip

0 commit comments

Comments
 (0)