blob: fe870b6c3094a962e09efb7afb7bc8baad778ac3 [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.
44 */
Pankaj Garg107a3802021-05-25 09:48:45 -070045class DLL_EXPORT ExchangeDelegate
Zang MingJiefbd2d102020-11-18 04:22:38 +080046{
47public:
Pankaj Garg107a3802021-05-25 09:48:45 -070048 virtual ~ExchangeDelegate() {}
Zang MingJiefbd2d102020-11-18 04:22:38 +080049
50 /**
51 * @brief
Boris Zbarsky6c172a22021-07-09 17:08:55 -040052 * This function is the protocol callback for handling a received CHIP
53 * message.
54 *
55 * After calling this method an exchange will close itself unless one of
56 * two things happens:
57 *
58 * 1) A call to SendMessage on the exchange with the kExpectResponse flag
59 * set.
60 * 2) A call to WillSendMessage on the exchange.
61 *
62 * Consumers that don't do one of those things MUST NOT retain a pointer
63 * to the exchange.
Zang MingJiefbd2d102020-11-18 04:22:38 +080064 *
65 * @param[in] ec A pointer to the ExchangeContext object.
Yufeng Wangfda8e092021-02-02 10:01:22 -080066 * @param[in] payloadHeader A reference to the PayloadHeader object.
Kevin Schoedelbc4f8412021-01-08 14:46:39 -050067 * @param[in] payload A handle to the PacketBuffer object holding the message payload.
Zang MingJiefbd2d102020-11-18 04:22:38 +080068 */
Zang MingJie2b2622f2021-09-10 20:59:20 +080069 virtual CHIP_ERROR OnMessageReceived(ExchangeContext * ec, const PayloadHeader & payloadHeader,
70 System::PacketBufferHandle && payload) = 0;
Zang MingJiefbd2d102020-11-18 04:22:38 +080071
72 /**
73 * @brief
74 * This function is the protocol callback to invoke when the timeout for the receipt
75 * of a response message has expired.
76 *
Boris Zbarsky94ce2b02021-07-15 14:03:31 -040077 * After calling this method an exchange will close itself unless one of
78 * two things happens:
79 *
80 * 1) A call to SendMessage on the exchange with the kExpectResponse flag
81 * set.
82 * 2) A call to WillSendMessage on the exchange.
83 *
84 * Consumers that don't do one of those things MUST NOT retain a pointer
85 * to the exchange.
86 *
Zang MingJiefbd2d102020-11-18 04:22:38 +080087 * @param[in] ec A pointer to the ExchangeContext object.
88 */
89 virtual void OnResponseTimeout(ExchangeContext * ec) = 0;
90
91 /**
92 * @brief
93 * This function is the protocol callback to invoke when the associated
Boris Zbarskye5bad6a2022-06-10 11:12:05 -040094 * exchange context is being closed.
95 *
96 * If the exchange was in a state where it was expecting a message to be
97 * sent due to an earlier WillSendMessage call or because the exchange has
98 * just been created as an initiator, the consumer is holding a reference
99 * to the exchange and it's the consumer's responsibility to call
100 * Release() on the exchange at some point. The usual way this happens is
101 * that the consumer tries to send its message, that fails, and the
102 * consumer calls Close() on the exchange. Calling Close() after an
103 * OnExchangeClosing() notification is allowed in this situation.
Zang MingJiefbd2d102020-11-18 04:22:38 +0800104 *
105 * @param[in] ec A pointer to the ExchangeContext object.
106 */
107 virtual void OnExchangeClosing(ExchangeContext * ec) {}
Pankaj Garg362c5f22021-04-14 16:35:15 -0700108
Zang MingJie9a80f752021-12-22 16:49:20 +0800109 virtual ExchangeMessageDispatch & GetMessageDispatch() { return ApplicationExchangeDispatch::Instance(); }
Zang MingJiefbd2d102020-11-18 04:22:38 +0800110};
111
Zang MingJied1512e52022-04-15 12:26:24 +0800112/**
113 * @brief
114 * This class handles unsolicited messages. The implementation can select an exchange delegate to use based on the payload header
115 * of the incoming message.
116 */
117class DLL_EXPORT UnsolicitedMessageHandler
118{
119public:
120 virtual ~UnsolicitedMessageHandler() {}
121
122 /**
123 * @brief
124 * This function handles an unsolicited CHIP message.
125 *
126 * If the implementation returns CHIP_NO_ERROR, it is expected to set newDelegate to the delegate to use for the exchange
127 * handling the message. The message layer will handle creating the exchange with this delegate.
128 *
129 * If the implementation returns an error, message processing will be aborted for this message.
130 *
131 * @param[in] payloadHeader A reference to the PayloadHeader object for the unsolicited message. The protocol and message
132 * type of this header match the UnsolicitedMessageHandler.
133 * @param[out] newDelegate A new exchange delegate to be used by the new exchange created to handle the message.
134 */
135 virtual CHIP_ERROR OnUnsolicitedMessageReceived(const PayloadHeader & payloadHeader, ExchangeDelegate *& newDelegate) = 0;
136
137 /**
138 * @brief
139 * This function is called when OnUnsolicitedMessageReceived successfully returns a new delegate, but the session manager
140 * fails to assign the delegate to a new exchange. It can be used to free the delegate as needed.
141 *
142 * Once an exchange is created with the delegate, the OnExchangeClosing notification can be used to free the delegate as
143 * needed.
144 *
145 * @param[in] delegate The exchange delegate to be released.
146 */
147 virtual void OnExchangeCreationFailed(ExchangeDelegate * delegate) {}
148};
149
Yufeng Wang01031e72020-12-01 09:57:42 -0800150} // namespace Messaging
Zang MingJiefbd2d102020-11-18 04:22:38 +0800151} // namespace chip