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, etc.).
      32              :  *
      33              :  * @warning Lifetime of Span-Referenced Data:
      34              :  * `SpanEndpoint` does NOT take ownership of the data arrays referenced by its
      35              :  * internal `chip::Span` members. The caller who provides these Spans (usually via the
      36              :  * `Builder`) MUST ensure that the underlying data remains valid for the entire lifetime
      37              :  * of the `SpanEndpoint` instance.
      38              :  *   - For `Span<T>` (e.g., `Span<const ClusterId>`, `Span<const DeviceTypeEntry>`), the
      39              :  *     array of `T` elements must outlive the `SpanEndpoint`.
      40              :  *   - For `Span<T*>` (e.g., `Span<ServerClusterInterface *>`), both the array of pointers
      41              :  *     (`T*`) and the objects (`T`) pointed to by those pointers must outlive the
      42              :  *     `SpanEndpoint`.
      43              :  * Failure to adhere to these lifetime requirements will lead to undefined behavior.
      44              :  */
      45              : class SpanEndpoint : public EndpointInterface
      46              : {
      47              : public:
      48              :     /**
      49              :      * @brief Builder class for constructing a SpanEndpoint.
      50              :      *
      51              :      * This class provides a way to set the client clusters, semantic tags,
      52              :      * and device types of the SpanEndpoint.
      53              :      */
      54              :     class Builder
      55              :     {
      56              :     public:
      57          157 :         explicit Builder() = default;
      58              : 
      59              :         Builder & SetClientClusters(Span<const ClusterId> clientClusters);
      60              :         Builder & SetDeviceTypes(Span<const DataModel::DeviceTypeEntry> deviceTypes);
      61              : 
      62              : #if CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID
      63              :         Builder & SetEndpointUniqueId(CharSpan endpointUniqueId);
      64              : #endif
      65              :         SpanEndpoint Build();
      66              : 
      67              :     private:
      68              :         Span<const ClusterId> mClientClusters;
      69              :         Span<const DataModel::DeviceTypeEntry> mDeviceTypes;
      70              : 
      71              : #if CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID
      72              :         CharSpan mEndpointUniqueId;
      73              : #endif
      74              :     };
      75              : 
      76          461 :     ~SpanEndpoint() override = default;
      77              : 
      78              :     // Delete copy constructor and assignment operator. SpanEndpoint holds non-owning data (Spans).
      79              :     // This helps prevent accidental copies that could lead multiple objects pointing to the same external data.
      80              :     SpanEndpoint(const SpanEndpoint &)             = delete;
      81              :     SpanEndpoint & operator=(const SpanEndpoint &) = delete;
      82              : 
      83              :     // Allow move semantics for SpanEndpoint.
      84          152 :     SpanEndpoint(SpanEndpoint &&)             = default;
      85              :     SpanEndpoint & operator=(SpanEndpoint &&) = default;
      86              : 
      87              :     // Iteration methods
      88              :     CHIP_ERROR DeviceTypes(ReadOnlyBufferBuilder<DataModel::DeviceTypeEntry> & out) const override;
      89              :     CHIP_ERROR ClientClusters(ReadOnlyBufferBuilder<ClusterId> & out) const override;
      90              : 
      91              : #if CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID
      92              :     CharSpan EndpointUniqueID() const override;
      93              : #endif
      94              : 
      95              : private:
      96              :     // Private constructor for Builder
      97              : #if CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID
      98              :     SpanEndpoint(const Span<const ClusterId> & clientClusters, const Span<const DataModel::DeviceTypeEntry> & deviceTypes,
      99              :                  const CharSpan & uniqueEndpointId);
     100              : #else
     101              :     SpanEndpoint(const Span<const ClusterId> & clientClusters, const Span<const DataModel::DeviceTypeEntry> & deviceTypes);
     102              : #endif
     103              : 
     104              :     // Iteration methods
     105              :     Span<const DataModel::DeviceTypeEntry> mDeviceTypes;
     106              :     Span<const ClusterId> mClientClusters;
     107              : 
     108              : #if CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID
     109              :     CharSpan mEndpointUniqueId;
     110              : #endif
     111              : };
     112              : 
     113              : } // namespace app
     114              : } // namespace chip