Line data    Source code

       1              : /*
       2              :  *    Copyright (c) 2025 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 <app/data-model-provider/MetadataTypes.h>
      20              : #include <data-model-providers/codedriven/endpoint/EndpointInterface.h>
      21              : #include <lib/core/DataModelTypes.h>
      22              : #include <lib/support/Span.h>
      23              : 
      24              : namespace chip {
      25              : namespace app {
      26              : 
      27              : /**
      28              :  * @brief An implementation of EndpointInterface that uses `chip::Span` to refer to its data.
      29              :  *
      30              :  * This provider is constructed using its `Builder` class. It stores `chip::Span` members that
      31              :  * point to externally managed arrays for its configuration (device types, server/client clusters,
      32              :  * semantic tags, etc.).
      33              :  *
      34              :  * @warning Lifetime of Span-Referenced Data:
      35              :  * `SpanEndpoint` does NOT take ownership of the data arrays referenced by its
      36              :  * internal `chip::Span` members. The caller who provides these Spans (usually via the
      37              :  * `Builder`) MUST ensure that the underlying data remains valid for the entire lifetime
      38              :  * of the `SpanEndpoint` instance.
      39              :  *   - For `Span<T>` (e.g., `Span<const ClusterId>`, `Span<const DeviceTypeEntry>`), the
      40              :  *     array of `T` elements must outlive the `SpanEndpoint`.
      41              :  *   - For `Span<T*>` (e.g., `Span<ServerClusterInterface *>`), both the array of pointers
      42              :  *     (`T*`) and the objects (`T`) pointed to by those pointers must outlive the
      43              :  *     `SpanEndpoint`.
      44              :  * Failure to adhere to these lifetime requirements will lead to undefined behavior.
      45              :  */
      46              : class SpanEndpoint : public EndpointInterface
      47              : {
      48              : public:
      49              :     /**
      50              :      * @brief Builder class for constructing a SpanEndpoint.
      51              :      *
      52              :      * This class provides a way to set the client clusters, semantic tags,
      53              :      * and device types of the SpanEndpoint.
      54              :      */
      55              :     class Builder
      56              :     {
      57              :     public:
      58          159 :         explicit Builder() = default;
      59              : 
      60              :         Builder & SetClientClusters(Span<const ClusterId> clientClusters);
      61              :         Builder & SetSemanticTags(Span<const SemanticTag> semanticTags);
      62              :         Builder & SetDeviceTypes(Span<const DataModel::DeviceTypeEntry> deviceTypes);
      63              : 
      64              :         SpanEndpoint Build();
      65              : 
      66              :     private:
      67              :         Span<const ClusterId> mClientClusters;
      68              :         Span<const SemanticTag> mSemanticTags;
      69              :         Span<const DataModel::DeviceTypeEntry> mDeviceTypes;
      70              :     };
      71              : 
      72          465 :     ~SpanEndpoint() override = default;
      73              : 
      74              :     // Delete copy constructor and assignment operator. SpanEndpoint holds non-owning data (Spans).
      75              :     // This helps prevent accidental copies that could lead multiple objects pointing to the same external data.
      76              :     SpanEndpoint(const SpanEndpoint &)             = delete;
      77              :     SpanEndpoint & operator=(const SpanEndpoint &) = delete;
      78              : 
      79              :     // Allow move semantics for SpanEndpoint.
      80          153 :     SpanEndpoint(SpanEndpoint &&)             = default;
      81              :     SpanEndpoint & operator=(SpanEndpoint &&) = default;
      82              : 
      83              :     // Iteration methods
      84              :     CHIP_ERROR SemanticTags(ReadOnlyBufferBuilder<SemanticTag> & out) const override;
      85              :     CHIP_ERROR DeviceTypes(ReadOnlyBufferBuilder<DataModel::DeviceTypeEntry> & out) const override;
      86              :     CHIP_ERROR ClientClusters(ReadOnlyBufferBuilder<ClusterId> & out) const override;
      87              : 
      88              : private:
      89              :     // Private constructor for Builder
      90              :     SpanEndpoint(const Span<const ClusterId> & clientClusters, const Span<const SemanticTag> & semanticTags,
      91              :                  const Span<const DataModel::DeviceTypeEntry> & deviceTypes);
      92              : 
      93              :     // Iteration methods
      94              :     Span<const DataModel::DeviceTypeEntry> mDeviceTypes;
      95              :     Span<const SemanticTag> mSemanticTags;
      96              :     Span<const ClusterId> mClientClusters;
      97              : };
      98              : 
      99              : } // namespace app
     100              : } // namespace chip