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              : #pragma once
      18              : 
      19              : #include <lib/core/CHIPError.h>
      20              : #include <lib/core/CriticalFailure.h>
      21              : #include <lib/support/StringBuilder.h>
      22              : #include <protocols/interaction_model/StatusCode.h>
      23              : 
      24              : #include <variant>
      25              : 
      26              : namespace chip {
      27              : namespace app {
      28              : namespace DataModel {
      29              : 
      30              : /// An ActionReturnStatus encodes the result of a read/write/invoke.
      31              : ///
      32              : /// Generally such actions result in a StatusIB in the interaction model,
      33              : /// which is a code (InteractionModel::Status) and may have an associated
      34              : /// cluster-specific code.
      35              : ///
      36              : /// However some actions specifically may return additional information for
      37              : /// chunking, hence the existence of this class:
      38              : ///
      39              : ///   - encapsulates a ClusterStatusCode for an actual action result
      40              : ///   - encapsulates a underlying CHIP_ERROR for reporting purposes
      41              : ///   - has a way to check for "chunking needed" status.
      42              : ///
      43              : /// The class is directly constructible from statuses (non-exlicit) to make
      44              : /// returning of values easy.
      45              : class ActionReturnStatus
      46              : {
      47              : public:
      48              :     // Provides additional statuses used for specific functionalities not necessarily covered
      49              :     // by the existing CHIP_ERROR or InteractionModel::Status
      50              :     enum class FixedStatus
      51              :     {
      52              :         kWriteSuccessNoOp,
      53              :     };
      54              :     /// Provides storage for the c_str() call for the action status.
      55              :     struct StringStorage
      56              :     {
      57              :         // Generally size should be sufficient.
      58              :         // The longest status code from StatusCodeList is NO_UPSTREAM_SUBSCRIPTION(197)
      59              :         // so we need space for one of:
      60              :         //    "NO_UPSTREAM_SUBSCRIPTION(197)\0" = 30   // explicit verbose status code
      61              :         //    "FAILURE(1), Code 255\0")                // cluster failure, verbose
      62              :         //    "SUCCESS(0), Code 255\0")                // cluster success, verbose
      63              :         //    "Status<197>, Code 255\0")               // Cluster failure, non-verbose
      64              :         //
      65              :         // CHIP_ERROR has its own (global/static!) storage
      66              :         chip::StringBuilder<32> formatBuffer;
      67              :     };
      68              : 
      69        17064 :     ActionReturnStatus(CHIP_ERROR error) : mReturnStatus(error) {}
      70            0 :     ActionReturnStatus(CriticalFailure error) : mReturnStatus(error) {}
      71         5605 :     ActionReturnStatus(Protocols::InteractionModel::Status status) :
      72         5605 :         mReturnStatus(Protocols::InteractionModel::ClusterStatusCode(status))
      73         5605 :     {}
      74           40 :     ActionReturnStatus(Protocols::InteractionModel::ClusterStatusCode status) : mReturnStatus(status) {}
      75           24 :     ActionReturnStatus(FixedStatus status) : mReturnStatus(status) {}
      76              : 
      77              :     /// Constructs a status code. Either returns the underlying code directly
      78              :     /// or converts the underlying CHIP_ERROR into a cluster status code.
      79              :     Protocols::InteractionModel::ClusterStatusCode GetStatusCode() const;
      80              : 
      81              :     /// Gets the underlying CHIP_ERROR if it exists, otherwise it will
      82              :     /// return a CHIP_ERROR corresponding to the underlying return status.
      83              :     ///
      84              :     /// Success statusess will result in CHIP_NO_ERROR (i.e. cluster specitic success codes are lost)
      85              :     CHIP_ERROR GetUnderlyingError() const;
      86              : 
      87              :     /// If this is a CHIP_NO_ERROR or a Status::Success
      88              :     bool IsSuccess() const;
      89              : 
      90              :     /// Considers if the underlying error is an error or not (CHIP_NO_ERROR is the only non-erro)
      91              :     /// or if the underlying statuscode is not an error (success and cluster specific successes
      92              :     /// are not an error).
      93         4935 :     bool IsError() const { return !IsSuccess(); }
      94              : 
      95              :     /// Checks if the underlying error is an out of space condition (i.e. something that
      96              :     /// chunking can handle by sending partial list data).
      97              :     ///
      98              :     /// Generally this is when the return is based on CHIP_ERROR_NO_MEMORY or CHIP_ERROR_BUFFER_TOO_SMALL
      99              :     bool IsOutOfSpaceEncodingResponse() const;
     100              : 
     101              :     /// Check if the operation was successful but shouldn't trigger any specific operation
     102              :     /// (e.g. overwriting an attribute with the same value).
     103              :     bool IsNoOpSuccess() const;
     104              : 
     105              :     // NOTE: operator== will treat a CHIP_GLOBAL_IM_ERROR and a raw cluster status as equal if the statuses match,
     106              :     //       even though a CHIP_ERROR has some formatting info like file/line
     107              :     bool operator==(const ActionReturnStatus & other) const;
     108           31 :     bool operator!=(const ActionReturnStatus & other) const { return !(*this == other); }
     109              : 
     110              :     /// Get the formatted string of this status.
     111              :     ///
     112              :     /// May use `storage` for storying the actual underlying character string.
     113              :     const char * c_str(StringStorage & storage) const;
     114              : 
     115              : private:
     116              :     std::variant<CHIP_ERROR, Protocols::InteractionModel::ClusterStatusCode, ActionReturnStatus::FixedStatus> mReturnStatus;
     117              : };
     118              : 
     119              : } // namespace DataModel
     120              : } // namespace app
     121              : } // namespace chip