blob: 97a5a0adaebb420e545dd499184a1aeed2445583 [file] [log] [blame]
Zang MingJiefbd2d102020-11-18 04:22:38 +08001/*
2 *
3 * Copyright (c) 2020 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
18/**
19 * @file
Yufeng Wanga369e892021-04-09 22:07:32 -070020 * This file defines the classes corresponding to CHIP Exchange Context Delegate.
Zang MingJiefbd2d102020-11-18 04:22:38 +080021 *
22 */
23
24#pragma once
25
Zang MingJie53dd5832021-09-03 03:05:16 +080026#include <lib/support/CHIPMem.h>
Pankaj Garg362c5f22021-04-14 16:35:15 -070027#include <messaging/ApplicationExchangeDispatch.h>
28#include <messaging/ExchangeMessageDispatch.h>
Zang MingJiefbd2d102020-11-18 04:22:38 +080029#include <system/SystemPacketBuffer.h>
Zang MingJieeca9bff2021-09-23 03:19:51 +080030#include <transport/SessionManager.h>
Zang MingJiefbd2d102020-11-18 04:22:38 +080031#include <transport/raw/MessageHeader.h>
32
33namespace chip {
Yufeng Wang01031e72020-12-01 09:57:42 -080034namespace Messaging {
Zang MingJiefbd2d102020-11-18 04:22:38 +080035
36class ExchangeContext;
37
38/**
39 * @brief
40 * This class provides a skeleton for the callback functions. The functions will be
41 * called by ExchangeContext object on specific events. If the user of ExchangeContext
42 * is interested in receiving these callbacks, they can specialize this class and handle
43 * each trigger in their implementation of this class.
Jerry Johnse1110c12022-07-21 00:15:40 -070044 *
45 * For consumers who use an ExchangeContext to send/receive protocol messages, there are specific
46 * expectations around who manages the exchange w.r.t clean-up and destruction:
47 * 1. When you allocate an exchange, you own the exchange. Until you send a message successfully, it's on you
48 * to release that ownership by calling Close or Abort on the exchange.
49 *
50 * 2. If you send a message successfully that doesn't require a response, the ownership transfers to
51 * the ExchangeMgr, and it will close the exchange for you automatically.
52 *
53 * 3. If you send a message successfully that does require a response and desire to close it before
54 * you get any notifications on that exchange from the ExchangeMgr, you should call Close or Abort on that exchange.
55 *
56 * 4. On reception of a message on an exchange, the ownership transfers to the OnMessageReceived callee.
57 * If you return from OnMessageReceived and no messages were sent on that exchange, the exchange will transfer back
58 * to the ExchangeMgr and it will automatically close it.
59 *
60 * 5. If you call WillSendMessage on the exchange in OnMessageReceived indicating a desire to send a message later
61 * on the exchange, then the exchange remains with you, and it's your responsibility to either send a message on it,
62 * or Close/Abort if you no longer wish to have the exchange around.
63 *
Jerry Johns55f90492022-08-29 01:14:05 -040064 * 6. If you get a call to OnExchangeClosing, you should null out your reference to the exchange UNLESS you still
65 * hold ownership of the exchange (i.e due to a prior call to WillSendMessage). In that case, you should call Abort/Close
66 * whenever you're done with using the exchange. Those calls can be made synchronously within the OnExchangeClosing
67 * callback.
Jerry Johnse1110c12022-07-21 00:15:40 -070068 *
Jerry Johns55f90492022-08-29 01:14:05 -040069 * 7. If you get a call to OnResponseTimeout, you should null out your reference to the exchange since the exchange layer
70 * owns the exchange and will handle releasing the ref later. A call to OnExchangeClosing will follow after.
Jerry Johnse1110c12022-07-21 00:15:40 -070071 *
Zang MingJiefbd2d102020-11-18 04:22:38 +080072 */
Pankaj Garg107a3802021-05-25 09:48:45 -070073class DLL_EXPORT ExchangeDelegate
Zang MingJiefbd2d102020-11-18 04:22:38 +080074{
75public:
Pankaj Garg107a3802021-05-25 09:48:45 -070076 virtual ~ExchangeDelegate() {}
Zang MingJiefbd2d102020-11-18 04:22:38 +080077
78 /**
79 * @brief
Boris Zbarsky6c172a22021-07-09 17:08:55 -040080 * This function is the protocol callback for handling a received CHIP
81 * message.
82 *
83 * After calling this method an exchange will close itself unless one of
84 * two things happens:
85 *
86 * 1) A call to SendMessage on the exchange with the kExpectResponse flag
87 * set.
88 * 2) A call to WillSendMessage on the exchange.
89 *
90 * Consumers that don't do one of those things MUST NOT retain a pointer
91 * to the exchange.
Zang MingJiefbd2d102020-11-18 04:22:38 +080092 *
93 * @param[in] ec A pointer to the ExchangeContext object.
Yufeng Wangfda8e092021-02-02 10:01:22 -080094 * @param[in] payloadHeader A reference to the PayloadHeader object.
Kevin Schoedelbc4f8412021-01-08 14:46:39 -050095 * @param[in] payload A handle to the PacketBuffer object holding the message payload.
Zang MingJiefbd2d102020-11-18 04:22:38 +080096 */
Zang MingJie2b2622f2021-09-10 20:59:20 +080097 virtual CHIP_ERROR OnMessageReceived(ExchangeContext * ec, const PayloadHeader & payloadHeader,
98 System::PacketBufferHandle && payload) = 0;
Zang MingJiefbd2d102020-11-18 04:22:38 +080099
100 /**
101 * @brief
102 * This function is the protocol callback to invoke when the timeout for the receipt
103 * of a response message has expired.
104 *
Boris Zbarsky94ce2b02021-07-15 14:03:31 -0400105 * After calling this method an exchange will close itself unless one of
106 * two things happens:
107 *
108 * 1) A call to SendMessage on the exchange with the kExpectResponse flag
109 * set.
110 * 2) A call to WillSendMessage on the exchange.
111 *
112 * Consumers that don't do one of those things MUST NOT retain a pointer
113 * to the exchange.
114 *
Zang MingJiefbd2d102020-11-18 04:22:38 +0800115 * @param[in] ec A pointer to the ExchangeContext object.
116 */
117 virtual void OnResponseTimeout(ExchangeContext * ec) = 0;
118
119 /**
120 * @brief
121 * This function is the protocol callback to invoke when the associated
Boris Zbarskye5bad6a2022-06-10 11:12:05 -0400122 * exchange context is being closed.
123 *
124 * If the exchange was in a state where it was expecting a message to be
125 * sent due to an earlier WillSendMessage call or because the exchange has
126 * just been created as an initiator, the consumer is holding a reference
127 * to the exchange and it's the consumer's responsibility to call
128 * Release() on the exchange at some point. The usual way this happens is
129 * that the consumer tries to send its message, that fails, and the
130 * consumer calls Close() on the exchange. Calling Close() after an
131 * OnExchangeClosing() notification is allowed in this situation.
Zang MingJiefbd2d102020-11-18 04:22:38 +0800132 *
133 * @param[in] ec A pointer to the ExchangeContext object.
134 */
135 virtual void OnExchangeClosing(ExchangeContext * ec) {}
Pankaj Garg362c5f22021-04-14 16:35:15 -0700136
Zang MingJie9a80f752021-12-22 16:49:20 +0800137 virtual ExchangeMessageDispatch & GetMessageDispatch() { return ApplicationExchangeDispatch::Instance(); }
Zang MingJiefbd2d102020-11-18 04:22:38 +0800138};
139
Zang MingJied1512e52022-04-15 12:26:24 +0800140/**
141 * @brief
142 * This class handles unsolicited messages. The implementation can select an exchange delegate to use based on the payload header
143 * of the incoming message.
144 */
145class DLL_EXPORT UnsolicitedMessageHandler
146{
147public:
148 virtual ~UnsolicitedMessageHandler() {}
149
150 /**
151 * @brief
152 * This function handles an unsolicited CHIP message.
153 *
154 * If the implementation returns CHIP_NO_ERROR, it is expected to set newDelegate to the delegate to use for the exchange
155 * handling the message. The message layer will handle creating the exchange with this delegate.
156 *
157 * If the implementation returns an error, message processing will be aborted for this message.
158 *
159 * @param[in] payloadHeader A reference to the PayloadHeader object for the unsolicited message. The protocol and message
160 * type of this header match the UnsolicitedMessageHandler.
161 * @param[out] newDelegate A new exchange delegate to be used by the new exchange created to handle the message.
162 */
163 virtual CHIP_ERROR OnUnsolicitedMessageReceived(const PayloadHeader & payloadHeader, ExchangeDelegate *& newDelegate) = 0;
164
165 /**
166 * @brief
167 * This function is called when OnUnsolicitedMessageReceived successfully returns a new delegate, but the session manager
168 * fails to assign the delegate to a new exchange. It can be used to free the delegate as needed.
169 *
170 * Once an exchange is created with the delegate, the OnExchangeClosing notification can be used to free the delegate as
171 * needed.
172 *
173 * @param[in] delegate The exchange delegate to be released.
174 */
175 virtual void OnExchangeCreationFailed(ExchangeDelegate * delegate) {}
176};
177
Yufeng Wang01031e72020-12-01 09:57:42 -0800178} // namespace Messaging
Zang MingJiefbd2d102020-11-18 04:22:38 +0800179} // namespace chip