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 "access/SubjectDescriptor.h"
      20              : #include "app/EventPathParams.h"
      21              : #include "lib/core/CHIPError.h"
      22              : #include <lib/core/TLVReader.h>
      23              : #include <lib/core/TLVWriter.h>
      24              : 
      25              : #include <app/AttributeValueDecoder.h>
      26              : #include <app/AttributeValueEncoder.h>
      27              : #include <app/CommandHandler.h>
      28              : 
      29              : #include <app/data-model-provider/ActionReturnStatus.h>
      30              : #include <app/data-model-provider/Context.h>
      31              : #include <app/data-model-provider/MetadataTypes.h>
      32              : #include <app/data-model-provider/OperationTypes.h>
      33              : 
      34              : namespace chip {
      35              : namespace app {
      36              : namespace DataModel {
      37              : 
      38              : /// Represents operations against a matter-defined data model.
      39              : ///
      40              : /// Class is SINGLE-THREADED:
      41              : ///   - operations are assumed to only be ever run in a single event-loop
      42              : ///     thread or equivalent
      43              : ///   - class is allowed to attempt to cache indexes/locations for faster
      44              : ///     lookups of things (e.g during iterations)
      45              : class Provider : public ProviderMetadataTree
      46              : {
      47              : public:
      48          160 :     virtual ~Provider() = default;
      49              : 
      50              :     // `context` pointers  will be guaranteed valid until Shutdown is called()
      51          215 :     virtual CHIP_ERROR Startup(InteractionModelContext context)
      52              :     {
      53          215 :         mContext = context;
      54          215 :         return CHIP_NO_ERROR;
      55              :     }
      56              :     virtual CHIP_ERROR Shutdown() = 0;
      57              : 
      58              :     // During the transition phase, we expect a large subset of code to require access to
      59              :     // event emitting, path marking and other operations
      60         2579 :     virtual InteractionModelContext CurrentContext() const { return mContext; }
      61              : 
      62              :     /// TEMPORARY/TRANSITIONAL requirement for transitioning from ember-specific code
      63              :     ///   ReadAttribute is REQUIRED to respond to GlobalAttribute read requests
      64              :     ///
      65              :     /// Return value notes:
      66              :     ///   ActionReturnStatus::IsOutOfSpaceEncodingResponse
      67              :     ///      - Indicates that list encoding had insufficient buffer space to encode elements.
      68              :     ///      - encoder::GetState().AllowPartialData() determines if these errors are permanent (no partial
      69              :     ///        data allowed) or further encoding can be retried (AllowPartialData true for list encoding)
      70              :     virtual ActionReturnStatus ReadAttribute(const ReadAttributeRequest & request, AttributeValueEncoder & encoder) = 0;
      71              : 
      72              :     /// Requests a write of an attribute.
      73              :     ///
      74              :     /// When this is invoked, caller is expected to have already done some validations:
      75              :     ///    - cluster `data version` has been checked for the incoming request if applicable
      76              :     ///
      77              :     /// TEMPORARY/TRANSITIONAL requirement for transitioning from ember-specific code
      78              :     ///   WriteAttribute is REQUIRED to perform:
      79              :     ///     - ACL validation (see notes on OperationFlags::kInternal)
      80              :     ///     - Validation of readability/writability (also controlled by OperationFlags::kInternal)
      81              :     ///     - Validation of timed interaction required (also controlled by OperationFlags::kInternal)
      82              :     virtual ActionReturnStatus WriteAttribute(const WriteAttributeRequest & request, AttributeValueDecoder & decoder) = 0;
      83              : 
      84              :     /// `handler` is used to send back the reply.
      85              :     ///    - returning `std::nullopt` means that return value was placed in handler directly.
      86              :     ///      This includes cases where command handling and value return will be done asynchronously.
      87              :     ///    - returning a value other than Success implies an error reply (error and data are mutually exclusive)
      88              :     ///
      89              :     /// Return value expectations:
      90              :     ///   - if a response has been placed into `handler` then std::nullopt MUST be returned. In particular
      91              :     ///     note that CHIP_NO_ERROR is NOT the same as std::nullopt:
      92              :     ///        > CHIP_NO_ERROR means handler had no status set and we expect the caller to AddStatus(success)
      93              :     ///        > std::nullopt means that handler has added an appropriate data/status response
      94              :     ///   - if a value is returned (not nullopt) then the handler response MUST NOT be filled. The caller
      95              :     ///     will then issue `handler->AddStatus(request.path, <return_value>->GetStatusCode())`. This is a
      96              :     ///     convenience to make writing Invoke calls easier.
      97              :     virtual std::optional<ActionReturnStatus> Invoke(const InvokeRequest & request, chip::TLV::TLVReader & input_arguments,
      98              :                                                      CommandHandler * handler) = 0;
      99              : 
     100              : private:
     101              :     InteractionModelContext mContext = { nullptr };
     102              : };
     103              : 
     104              : } // namespace DataModel
     105              : } // namespace app
     106              : } // namespace chip