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            1 :     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, constructing a
      69              :      *   StatusIB from the error 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