Line data    Source code

       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           0 :     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           0 :     virtual void OnResponse(CommandSender * apCommandSender, const ConcreteCommandPath & aPath, const StatusIB & aStatusIB,
      58             :                             TLV::TLVReader * apData)
      59           0 :     {}
      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           0 :     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