Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 1 | /* |
| 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 Wang | a369e89 | 2021-04-09 22:07:32 -0700 | [diff] [blame] | 20 | * This file defines the classes corresponding to CHIP Exchange Context Delegate. |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 21 | * |
| 22 | */ |
| 23 | |
| 24 | #pragma once |
| 25 | |
Zang MingJie | 53dd583 | 2021-09-03 03:05:16 +0800 | [diff] [blame] | 26 | #include <lib/support/CHIPMem.h> |
Pankaj Garg | 362c5f2 | 2021-04-14 16:35:15 -0700 | [diff] [blame] | 27 | #include <messaging/ApplicationExchangeDispatch.h> |
| 28 | #include <messaging/ExchangeMessageDispatch.h> |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 29 | #include <system/SystemPacketBuffer.h> |
Zang MingJie | eca9bff | 2021-09-23 03:19:51 +0800 | [diff] [blame] | 30 | #include <transport/SessionManager.h> |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 31 | #include <transport/raw/MessageHeader.h> |
| 32 | |
| 33 | namespace chip { |
Yufeng Wang | 01031e7 | 2020-12-01 09:57:42 -0800 | [diff] [blame] | 34 | namespace Messaging { |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 35 | |
| 36 | class 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 Johns | e1110c1 | 2022-07-21 00:15:40 -0700 | [diff] [blame] | 44 | * |
| 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 Johns | 55f9049 | 2022-08-29 01:14:05 -0400 | [diff] [blame] | 64 | * 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 Johns | e1110c1 | 2022-07-21 00:15:40 -0700 | [diff] [blame] | 68 | * |
Jerry Johns | 55f9049 | 2022-08-29 01:14:05 -0400 | [diff] [blame] | 69 | * 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 Johns | e1110c1 | 2022-07-21 00:15:40 -0700 | [diff] [blame] | 71 | * |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 72 | */ |
Pankaj Garg | 107a380 | 2021-05-25 09:48:45 -0700 | [diff] [blame] | 73 | class DLL_EXPORT ExchangeDelegate |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 74 | { |
| 75 | public: |
Pankaj Garg | 107a380 | 2021-05-25 09:48:45 -0700 | [diff] [blame] | 76 | virtual ~ExchangeDelegate() {} |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 77 | |
| 78 | /** |
| 79 | * @brief |
Boris Zbarsky | 6c172a2 | 2021-07-09 17:08:55 -0400 | [diff] [blame] | 80 | * 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 MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 92 | * |
| 93 | * @param[in] ec A pointer to the ExchangeContext object. |
Yufeng Wang | fda8e09 | 2021-02-02 10:01:22 -0800 | [diff] [blame] | 94 | * @param[in] payloadHeader A reference to the PayloadHeader object. |
Kevin Schoedel | bc4f841 | 2021-01-08 14:46:39 -0500 | [diff] [blame] | 95 | * @param[in] payload A handle to the PacketBuffer object holding the message payload. |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 96 | */ |
Zang MingJie | 2b2622f | 2021-09-10 20:59:20 +0800 | [diff] [blame] | 97 | virtual CHIP_ERROR OnMessageReceived(ExchangeContext * ec, const PayloadHeader & payloadHeader, |
| 98 | System::PacketBufferHandle && payload) = 0; |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 99 | |
| 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 Zbarsky | 94ce2b0 | 2021-07-15 14:03:31 -0400 | [diff] [blame] | 105 | * 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 MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 115 | * @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 Zbarsky | e5bad6a | 2022-06-10 11:12:05 -0400 | [diff] [blame] | 122 | * 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 MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 132 | * |
| 133 | * @param[in] ec A pointer to the ExchangeContext object. |
| 134 | */ |
| 135 | virtual void OnExchangeClosing(ExchangeContext * ec) {} |
Pankaj Garg | 362c5f2 | 2021-04-14 16:35:15 -0700 | [diff] [blame] | 136 | |
Zang MingJie | 9a80f75 | 2021-12-22 16:49:20 +0800 | [diff] [blame] | 137 | virtual ExchangeMessageDispatch & GetMessageDispatch() { return ApplicationExchangeDispatch::Instance(); } |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 138 | }; |
| 139 | |
Zang MingJie | d1512e5 | 2022-04-15 12:26:24 +0800 | [diff] [blame] | 140 | /** |
| 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 | */ |
| 145 | class DLL_EXPORT UnsolicitedMessageHandler |
| 146 | { |
| 147 | public: |
| 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 Wang | 01031e7 | 2020-12-01 09:57:42 -0800 | [diff] [blame] | 178 | } // namespace Messaging |
Zang MingJie | fbd2d10 | 2020-11-18 04:22:38 +0800 | [diff] [blame] | 179 | } // namespace chip |