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/ConcreteAttributePath.h>
      21              : #include <app/ConcreteCommandPath.h>
      22              : #include <lib/core/DataModelTypes.h>
      23              : #include <lib/support/BitFlags.h>
      24              : 
      25              : #include <cstdint>
      26              : #include <optional>
      27              : 
      28              : namespace chip {
      29              : namespace app {
      30              : namespace DataModel {
      31              : 
      32              : /// Contains common flags among all interaction model operations: read/write/invoke
      33              : enum class OperationFlags : uint32_t
      34              : {
      35              :     // NOTE: temporary flag. This flag exists to faciliate transition from ember-compatibilty-functions
      36              :     //       implementation to DataModel Interface functionality. Specifically currently the
      37              :     //       model is expected to perform ACL and readability/writability checks.
      38              :     //
      39              :     //       In the future, this flag will be removed and InteractionModelEngine/ReportingEngine
      40              :     //       will perform the required validation.
      41              :     //
      42              :     //       Currently the flag FORCES a bypass of:
      43              :     //         - ACL validation (will allow any read/write)
      44              :     //         - Access validation (will allow reading write-only data for example)
      45              :     kInternal = 0x0001,
      46              : };
      47              : 
      48              : /// This information is available for ALL interactions: read/write/invoke
      49              : struct OperationRequest
      50              : {
      51              :     BitFlags<OperationFlags> operationFlags;
      52              : 
      53              :     /// Current authentication data EXCEPT for internal requests.
      54              :     ///  - Non-internal requests MUST have this set.
      55              :     ///  - operationFlags.Has(OperationFlags::kInternal) MUST NOT have this set
      56              :     ///
      57              :     /// NOTE: once kInternal flag is removed, this will become non-optional
      58              :     const chip::Access::SubjectDescriptor * subjectDescriptor = nullptr;
      59              : 
      60              :     /// Accessing fabric index is the subjectDescriptor fabric index (if any).
      61              :     /// This is a readability convenience function.
      62              :     ///
      63              :     /// Returns kUndefinedFabricIndex if no subject descriptor is available
      64            0 :     FabricIndex GetAccessingFabricIndex() const
      65              :     {
      66            0 :         VerifyOrReturnValue(subjectDescriptor != nullptr, kUndefinedFabricIndex);
      67            0 :         return subjectDescriptor->fabricIndex;
      68              :     }
      69              : };
      70              : 
      71              : enum class ReadFlags : uint32_t
      72              : {
      73              :     kFabricFiltered = 0x0001, // reading is performed fabric-filtered
      74              : };
      75              : 
      76              : struct ReadAttributeRequest : OperationRequest
      77              : {
      78              :     ConcreteAttributePath path;
      79              :     BitFlags<ReadFlags> readFlags;
      80              : };
      81              : 
      82              : enum class WriteFlags : uint32_t
      83              : {
      84              :     kTimed = 0x0001, // Write is a timed write (i.e. a Timed Request Action preceeded it)
      85              : };
      86              : 
      87              : struct WriteAttributeRequest : OperationRequest
      88              : {
      89              :     ConcreteDataAttributePath path; // NOTE: this also contains LIST operation options (i.e. "data" path type)
      90              :     BitFlags<WriteFlags> writeFlags;
      91              : 
      92              :     // The path of the previous successful write in the same write transaction, if any.
      93              :     //
      94              :     // In particular this means that a write to this path has succeeded before (i.e. it passed required ACL checks).
      95              :     // The intent for this is to allow short-cutting ACL checks when ACL is in progress of being updated:
      96              :     //   - During write chunking, list writes can be of the form "reset list" followed by "append item by item"
      97              :     //   - When ACL is updating, a reset to empty would result in the entire ACL being deny and the "append"
      98              :     //     would fail.
      99              :     // callers are expected to keep track of a `previousSuccessPath` whenever a write succeeds (otherwise ACL
     100              :     // checks may fail)
     101              :     std::optional<ConcreteAttributePath> previousSuccessPath;
     102              : };
     103              : 
     104              : enum class InvokeFlags : uint32_t
     105              : {
     106              :     kTimed = 0x0001, // Command received as part of a timed invoke interaction.
     107              : };
     108              : 
     109              : struct InvokeRequest : OperationRequest
     110              : {
     111              :     ConcreteCommandPath path;
     112              :     BitFlags<InvokeFlags> invokeFlags;
     113              : };
     114              : 
     115              : } // namespace DataModel
     116              : } // namespace app
     117              : } // namespace chip