src/app/AttributeValueEncoder.h - third_party/github/project-chip/connectedhomeip - Git at Google

 /*
  *    Copyright (c) 2021-2024 Project CHIP Authors
  *    All rights reserved.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
  *    You may obtain a copy of the License at
  *
  *        http://www.apache.org/licenses/LICENSE-2.0
  *
  *    Unless required by applicable law or agreed to in writing, software
  *    distributed under the License is distributed on an "AS IS" BASIS,
  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *    See the License for the specific language governing permissions and
  *    limitations under the License.
  */
 #pragma once

 #include <access/SubjectDescriptor.h>
 #include <app/AttributeEncodeState.h>
 #include <app/AttributeReportBuilder.h>
 #include <app/ConcreteAttributePath.h>
 #include <app/MessageDef/AttributeReportIBs.h>
 #include <app/data-model/FabricScoped.h>
 #include <app/data-model/List.h>
 #include <lib/support/BitFlags.h>
 #include <lib/support/BitMask.h>
 #include <lib/support/TypeTraits.h>

 #include <type_traits>

 namespace chip {
 namespace app {

 /**
  * The AttributeValueEncoder is a helper class for filling report payloads into AttributeReportIBs.
  * The attribute value encoder can be initialized with a AttributeEncodeState for saving and recovering its state between encode
  * sessions (chunkings).
  *
  * When Encode returns recoverable errors (e.g. CHIP_ERROR_NO_MEMORY) the state can be used to initialize the AttributeValueEncoder
  * for future use on the same attribute path.
  */
 class AttributeValueEncoder
 {
 private:
     // Attempt to save flash by reducing the number of instantiations of the
     // Encode methods for AttributeValueEncoder and ListEncodeHelper.  The idea
     // here is that some types actually end up encoded as other types anyway
     // (e.g. all integers are encoded are uint64_t or int64_t), so we might as
     // well avoid generating template instantiations of our methods (which have
     // extra logic) for all the different types that end up encoded the same in
     // the end.
     //
     // A type is a "base" type if it can't be treated as any other type for
     // encoding purposes.  Overloads of BaseEncodableValue can be added for
     // "non-base" types to return values of a base type.
     //
     // It's important here to not collapse together types for which
     // DataModel::Encode in fact has different behavior (e.g. enum types).
     template <typename T>
     static constexpr const T & BaseEncodableValue(const T & aArg)
     {
         return aArg;
     }
     template <typename T>
     static constexpr auto BaseEncodableValue(const BitFlags<T> & aArg)
     {
         return BaseEncodableValue(aArg.Raw());
     }
     template <typename T>
     static constexpr auto BaseEncodableValue(const BitMask<T> & aArg)
     {
         return BaseEncodableValue(aArg.Raw());
     }
     static constexpr uint64_t BaseEncodableValue(uint32_t aArg) { return aArg; }
     static constexpr uint64_t BaseEncodableValue(uint16_t aArg) { return aArg; }
     static constexpr uint64_t BaseEncodableValue(uint8_t aArg) { return aArg; }
     static constexpr int64_t BaseEncodableValue(int32_t aArg) { return aArg; }
     static constexpr int64_t BaseEncodableValue(int16_t aArg) { return aArg; }
     static constexpr int64_t BaseEncodableValue(int8_t aArg) { return aArg; }

     // Determines whether a type should be encoded as-is (if IsBaseType<T> is
     // true) or transformed to a different type by calling BaseEncodableValue()
     // on it.
     template <typename T>
     static constexpr bool IsBaseType = std::is_same_v<const T &, decltype(BaseEncodableValue(std::declval<const T &>()))>;

     template <typename T>
     static constexpr bool IsMatterEnum = std::is_enum_v<T> && DataModel::detail::HasUnknownValue<T>;

 public:
     class ListEncodeHelper
     {
     public:
         ListEncodeHelper(AttributeValueEncoder & encoder) : mAttributeValueEncoder(encoder) {}

         template <typename T, std::enable_if_t<IsBaseType<T> && DataModel::IsFabricScoped<T>::value, bool> = true>
         CHIP_ERROR Encode(const T & aArg) const
         {
             VerifyOrReturnError(aArg.GetFabricIndex() != kUndefinedFabricIndex, CHIP_ERROR_INVALID_FABRIC_INDEX);

             // If we are encoding for a fabric filtered attribute read and the fabric index does not match that present in the
             // request, skip encoding this list item.
             VerifyOrReturnError(!mAttributeValueEncoder.mIsFabricFiltered ||
                                     aArg.GetFabricIndex() == mAttributeValueEncoder.AccessingFabricIndex(),
                                 CHIP_NO_ERROR);
             return mAttributeValueEncoder.EncodeListItem(mCheckpoint, aArg, mAttributeValueEncoder.AccessingFabricIndex());
         }

         template <typename T,
                   std::enable_if_t<IsBaseType<T> && !DataModel::IsFabricScoped<T>::value && !IsMatterEnum<T>, bool> = true>
         CHIP_ERROR Encode(const T & aArg) const
         {
             return mAttributeValueEncoder.EncodeListItem(mCheckpoint, aArg);
         }

         // Specialization for enums to share as much code as possible in attribute encoding while
         // still doing the "unknown value" checks that might be needed..
         template <typename T, std::enable_if_t<IsBaseType<T> && IsMatterEnum<T>, bool> = true>
         CHIP_ERROR Encode(const T & aArg) const
         {
             static_assert(!DataModel::IsFabricScoped<T>::value, "How do we have a fabric-scoped enum?");
             using UnderlyingType = std::remove_cv_t<std::remove_reference_t<decltype(to_underlying(aArg))>>;
             static_assert(!std::is_same_v<UnderlyingType, T>, "Encode will call itself recursively");

             CHIP_DM_ENCODING_MAYBE_FAIL_UNKNOWN_ENUM_VALUE(aArg);

             return Encode(to_underlying(aArg));
         }

         template <typename T, std::enable_if_t<!IsBaseType<T>, bool> = true>
         CHIP_ERROR Encode(const T & aArg) const
         {
             return Encode(BaseEncodableValue(aArg));
         }

     private:
         AttributeValueEncoder & mAttributeValueEncoder;
         // Avoid calling the TLVWriter constructor for every instantiation of
         // EncodeListItem.  We treat encoding as a const operation, so either
         // have to put this on the stack (in which case it's per-instantiation),
         // or have it as mutable state.
         mutable TLV::TLVWriter mCheckpoint;
     };

     AttributeValueEncoder(AttributeReportIBs::Builder & aAttributeReportIBsBuilder, Access::SubjectDescriptor subjectDescriptor,
                           const ConcreteAttributePath & aPath, DataVersion aDataVersion, bool aIsFabricFiltered = false,
                           const AttributeEncodeState & aState = AttributeEncodeState()) :
         mAttributeReportIBsBuilder(aAttributeReportIBsBuilder),
         mSubjectDescriptor(subjectDescriptor), mPath(aPath.mEndpointId, aPath.mClusterId, aPath.mAttributeId),
         mDataVersion(aDataVersion), mIsFabricFiltered(aIsFabricFiltered), mEncodeState(aState)
     {}

     /**
      * Encode a single value.  This value will not be chunked; it will either be
      * entirely encoded or fail to be encoded.  Consumers are allowed to make
      * either one call to Encode or one call to EncodeList to handle a read.
      */
     template <typename T, std::enable_if_t<IsBaseType<T> && !IsMatterEnum<T>, bool> = true>
     CHIP_ERROR Encode(const T & aArg)
     {
         mTriedEncode = true;
         return EncodeAttributeReportIB(aArg);
     }

     template <typename T, std::enable_if_t<IsBaseType<T> && IsMatterEnum<T>, bool> = true>
     CHIP_ERROR Encode(const T & aArg)
     {
         using UnderlyingType = std::remove_cv_t<std::remove_reference_t<decltype(to_underlying(aArg))>>;
         static_assert(!std::is_same_v<UnderlyingType, T>, "Encode will call itself recursively");

         CHIP_DM_ENCODING_MAYBE_FAIL_UNKNOWN_ENUM_VALUE(aArg);

         return Encode(to_underlying(aArg));
     }

     template <typename T, std::enable_if_t<!IsBaseType<T>, bool> = true>
     CHIP_ERROR Encode(const T & aArg)
     {
         return Encode(BaseEncodableValue(aArg));
     }

     /**
      * Encode an explicit null value.
      */
     CHIP_ERROR EncodeNull()
     {
         // Doesn't matter what type Nullable we use here.
         return Encode(DataModel::Nullable<uint8_t>());
     }

     /**
      * Encode an explicit empty list.
      */
     CHIP_ERROR EncodeEmptyList()
     {
         // Doesn't matter what type List we use here.
         return Encode(DataModel::List<uint8_t>());
     }

     /**
      * aCallback is expected to take a const auto & argument and Encode() on it as many times as needed to encode all the list
      * elements one by one.  If any of those Encode() calls returns failure, aCallback must stop encoding and return failure.  When
      * all items are encoded aCallback is expected to return success.
      *
      * aCallback may not be called.  Consumers must not assume it will be called.
      *
      * When EncodeList returns an error, the consumers must abort the encoding, and return the exact error to the caller.
      *
      * TODO: Can we hold a error state in the AttributeValueEncoder itself?
      *
      * Consumers are allowed to make either one call to EncodeList or one call to Encode to handle a read.
      *
      */
     template <typename ListGenerator>
     CHIP_ERROR EncodeList(ListGenerator aCallback)
     {
         mTriedEncode = true;
         // Spec 10.5.4.3.1, 10.5.4.6 (Replace a list w/ Multiple IBs)
         // EmptyList acts as the beginning of the whole array type attribute report.
         // An empty list is encoded iff both mCurrentEncodingListIndex and mEncodeState.mCurrentEncodingListIndex are invalid
         // values. After encoding the empty list, mEncodeState.mCurrentEncodingListIndex and mCurrentEncodingListIndex are set to 0.
         ReturnErrorOnFailure(EnsureListStarted());
         CHIP_ERROR err = aCallback(ListEncodeHelper(*this));

         // Even if encoding list items failed, make sure we EnsureListEnded().
         // Since we encode list items atomically, in the case when we just
         // didn't fit the next item we want to make sure our list is properly
         // ended before the reporting engine starts chunking.
         EnsureListEnded();
         if (err == CHIP_NO_ERROR)
         {
             // The Encode procedure finished without any error, clear the state.
             mEncodeState.Reset();
         }
         return err;
     }

     bool TriedEncode() const { return mTriedEncode; }

     const Access::SubjectDescriptor & GetSubjectDescriptor() const { return mSubjectDescriptor; }

     /**
      * The accessing fabric index for this read or subscribe interaction.
      */
     FabricIndex AccessingFabricIndex() const { return GetSubjectDescriptor().fabricIndex; }

     /**
      * AttributeValueEncoder is a short lived object, and the state is persisted by mEncodeState and restored by constructor.
      */
     const AttributeEncodeState & GetState() const { return mEncodeState; }

 private:
     // We made EncodeListItem() private, and ListEncoderHelper will expose it by Encode()
     friend class ListEncodeHelper;
     friend class TestOnlyAttributeValueEncoderAccessor;

     // Returns true if the list item should be encoded.  If it should, the
     // passed-in TLVWriter will be used to checkpoint the current state of our
     // attribute report list builder.
     bool ShouldEncodeListItem(TLV::TLVWriter & aCheckpoint);

     // Does any cleanup work needed after attempting to encode a list item.
     void PostEncodeListItem(CHIP_ERROR aEncodeStatus, const TLV::TLVWriter & aCheckpoint);

     // EncodeListItem may be given an extra FabricIndex argument as a second
     // arg, or not.  Represent that via a parameter pack (which might be
     // empty). In practice, for any given ItemType the extra arg is either there
     // or not, so we don't get more template explosion due to aExtraArgs.
     template <typename ItemType, typename... ExtraArgTypes>
     CHIP_ERROR EncodeListItem(TLV::TLVWriter & aCheckpoint, const ItemType & aItem, ExtraArgTypes &&... aExtraArgs)
     {
         if (!ShouldEncodeListItem(aCheckpoint))
         {
             return CHIP_NO_ERROR;
         }

         CHIP_ERROR err;
         if (mEncodingInitialList)
         {
             // Just encode a single item, with an anonymous tag.
             AttributeReportBuilder builder;
             err = builder.EncodeValue(mAttributeReportIBsBuilder, TLV::AnonymousTag(), aItem,
                                       std::forward<ExtraArgTypes>(aExtraArgs)...);
         }
         else
         {
             err = EncodeAttributeReportIB(aItem, std::forward<ExtraArgTypes>(aExtraArgs)...);
         }

         PostEncodeListItem(err, aCheckpoint);
         return err;
     }

     /**
      * Builds a single AttributeReportIB in AttributeReportIBs.  The caller is
      * responsible for setting up mPath correctly.
      *
      * In particular, when we are encoding a single element in the list, mPath
      * must indicate a null list index to represent an "append" operation.
      * operation.
      *
      * EncodeAttributeReportIB may be given an extra FabricIndex argument as a second
      * arg, or not.  Represent that via a parameter pack (which might be
      * empty). In practice, for any given ItemType the extra arg is either
      * there or not, so we don't get more template explosion due to aExtraArgs.
      */
     template <typename ItemType, typename... ExtraArgTypes>
     CHIP_ERROR EncodeAttributeReportIB(const ItemType & aItem, ExtraArgTypes &&... aExtraArgs)
     {
         AttributeReportBuilder builder;
         ReturnErrorOnFailure(builder.PrepareAttribute(mAttributeReportIBsBuilder, mPath, mDataVersion));
         ReturnErrorOnFailure(builder.EncodeValue(mAttributeReportIBsBuilder, TLV::ContextTag(AttributeDataIB::Tag::kData), aItem,
                                                  std::forward<ExtraArgTypes>(aExtraArgs)...));

         return builder.FinishAttribute(mAttributeReportIBsBuilder);
     }

     /**
      * EnsureListStarted sets our mCurrentEncodingListIndex to 0, and:
      *
      * * If we are just starting the list, gets us ready to encode list items.
      *
      * * If we are continuing a chunked list, guarantees that mPath.mListOp is
      *   AppendItem after it returns.
      */
     CHIP_ERROR EnsureListStarted();

     /**
      * EnsureListEnded writes out the end of the list and our attribute data IB,
      * if we were encoding our initial list
      */
     void EnsureListEnded();

     AttributeReportIBs::Builder & mAttributeReportIBsBuilder;
     const Access::SubjectDescriptor mSubjectDescriptor;
     ConcreteDataAttributePath mPath;
     DataVersion mDataVersion;
     bool mTriedEncode      = false;
     bool mIsFabricFiltered = false;
     // mEncodingInitialList is true if we're encoding a list and we have not
     // started chunking it yet, so we're encoding a single attribute report IB
     // for the whole list, not one per item.
     bool mEncodingInitialList = false;
     // mEncodedAtLeastOneListItem becomes true once we successfully encode a list item.
     bool mEncodedAtLeastOneListItem     = false;
     ListIndex mCurrentEncodingListIndex = kInvalidListIndex;
     AttributeEncodeState mEncodeState;
 };

 } // namespace app
 } // namespace chip
	/*
	* Copyright (c) 2021-2024 Project CHIP Authors
	* All rights reserved.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	#pragma once

	#include <access/SubjectDescriptor.h>
	#include <app/AttributeEncodeState.h>
	#include <app/AttributeReportBuilder.h>
	#include <app/ConcreteAttributePath.h>
	#include <app/MessageDef/AttributeReportIBs.h>
	#include <app/data-model/FabricScoped.h>
	#include <app/data-model/List.h>
	#include <lib/support/BitFlags.h>
	#include <lib/support/BitMask.h>
	#include <lib/support/TypeTraits.h>

	#include <type_traits>

	namespace chip {
	namespace app {

	/**
	* The AttributeValueEncoder is a helper class for filling report payloads into AttributeReportIBs.
	* The attribute value encoder can be initialized with a AttributeEncodeState for saving and recovering its state between encode
	* sessions (chunkings).
	*
	* When Encode returns recoverable errors (e.g. CHIP_ERROR_NO_MEMORY) the state can be used to initialize the AttributeValueEncoder
	* for future use on the same attribute path.
	*/
	class AttributeValueEncoder
	{
	private:
	// Attempt to save flash by reducing the number of instantiations of the
	// Encode methods for AttributeValueEncoder and ListEncodeHelper. The idea
	// here is that some types actually end up encoded as other types anyway
	// (e.g. all integers are encoded are uint64_t or int64_t), so we might as
	// well avoid generating template instantiations of our methods (which have
	// extra logic) for all the different types that end up encoded the same in
	// the end.
	//
	// A type is a "base" type if it can't be treated as any other type for
	// encoding purposes. Overloads of BaseEncodableValue can be added for
	// "non-base" types to return values of a base type.
	//
	// It's important here to not collapse together types for which
	// DataModel::Encode in fact has different behavior (e.g. enum types).
	template <typename T>
	static constexpr const T & BaseEncodableValue(const T & aArg)
	{
	return aArg;
	}
	template <typename T>
	static constexpr auto BaseEncodableValue(const BitFlags<T> & aArg)
	{
	return BaseEncodableValue(aArg.Raw());
	}
	template <typename T>
	static constexpr auto BaseEncodableValue(const BitMask<T> & aArg)
	{
	return BaseEncodableValue(aArg.Raw());
	}
	static constexpr uint64_t BaseEncodableValue(uint32_t aArg) { return aArg; }
	static constexpr uint64_t BaseEncodableValue(uint16_t aArg) { return aArg; }
	static constexpr uint64_t BaseEncodableValue(uint8_t aArg) { return aArg; }
	static constexpr int64_t BaseEncodableValue(int32_t aArg) { return aArg; }
	static constexpr int64_t BaseEncodableValue(int16_t aArg) { return aArg; }
	static constexpr int64_t BaseEncodableValue(int8_t aArg) { return aArg; }

	// Determines whether a type should be encoded as-is (if IsBaseType<T> is
	// true) or transformed to a different type by calling BaseEncodableValue()
	// on it.
	template <typename T>
	static constexpr bool IsBaseType = std::is_same_v<const T &, decltype(BaseEncodableValue(std::declval<const T &>()))>;

	template <typename T>
	static constexpr bool IsMatterEnum = std::is_enum_v<T> && DataModel::detail::HasUnknownValue<T>;

	public:
	class ListEncodeHelper
	{
	public:
	ListEncodeHelper(AttributeValueEncoder & encoder) : mAttributeValueEncoder(encoder) {}

	template <typename T, std::enable_if_t<IsBaseType<T> && DataModel::IsFabricScoped<T>::value, bool> = true>
	CHIP_ERROR Encode(const T & aArg) const
	{
	VerifyOrReturnError(aArg.GetFabricIndex() != kUndefinedFabricIndex, CHIP_ERROR_INVALID_FABRIC_INDEX);

	// If we are encoding for a fabric filtered attribute read and the fabric index does not match that present in the
	// request, skip encoding this list item.
	VerifyOrReturnError(!mAttributeValueEncoder.mIsFabricFiltered \|\|
	aArg.GetFabricIndex() == mAttributeValueEncoder.AccessingFabricIndex(),
	CHIP_NO_ERROR);
	return mAttributeValueEncoder.EncodeListItem(mCheckpoint, aArg, mAttributeValueEncoder.AccessingFabricIndex());
	}

	template <typename T,
	std::enable_if_t<IsBaseType<T> && !DataModel::IsFabricScoped<T>::value && !IsMatterEnum<T>, bool> = true>
	CHIP_ERROR Encode(const T & aArg) const
	{
	return mAttributeValueEncoder.EncodeListItem(mCheckpoint, aArg);
	}

	// Specialization for enums to share as much code as possible in attribute encoding while
	// still doing the "unknown value" checks that might be needed..
	template <typename T, std::enable_if_t<IsBaseType<T> && IsMatterEnum<T>, bool> = true>
	CHIP_ERROR Encode(const T & aArg) const
	{
	static_assert(!DataModel::IsFabricScoped<T>::value, "How do we have a fabric-scoped enum?");
	using UnderlyingType = std::remove_cv_t<std::remove_reference_t<decltype(to_underlying(aArg))>>;
	static_assert(!std::is_same_v<UnderlyingType, T>, "Encode will call itself recursively");

	CHIP_DM_ENCODING_MAYBE_FAIL_UNKNOWN_ENUM_VALUE(aArg);

	return Encode(to_underlying(aArg));
	}

	template <typename T, std::enable_if_t<!IsBaseType<T>, bool> = true>
	CHIP_ERROR Encode(const T & aArg) const
	{
	return Encode(BaseEncodableValue(aArg));
	}

	private:
	AttributeValueEncoder & mAttributeValueEncoder;
	// Avoid calling the TLVWriter constructor for every instantiation of
	// EncodeListItem. We treat encoding as a const operation, so either
	// have to put this on the stack (in which case it's per-instantiation),
	// or have it as mutable state.
	mutable TLV::TLVWriter mCheckpoint;
	};

	AttributeValueEncoder(AttributeReportIBs::Builder & aAttributeReportIBsBuilder, Access::SubjectDescriptor subjectDescriptor,
	const ConcreteAttributePath & aPath, DataVersion aDataVersion, bool aIsFabricFiltered = false,
	const AttributeEncodeState & aState = AttributeEncodeState()) :
	mAttributeReportIBsBuilder(aAttributeReportIBsBuilder),
	mSubjectDescriptor(subjectDescriptor), mPath(aPath.mEndpointId, aPath.mClusterId, aPath.mAttributeId),
	mDataVersion(aDataVersion), mIsFabricFiltered(aIsFabricFiltered), mEncodeState(aState)
	{}

	/**
	* Encode a single value. This value will not be chunked; it will either be
	* entirely encoded or fail to be encoded. Consumers are allowed to make
	* either one call to Encode or one call to EncodeList to handle a read.
	*/
	template <typename T, std::enable_if_t<IsBaseType<T> && !IsMatterEnum<T>, bool> = true>
	CHIP_ERROR Encode(const T & aArg)
	{
	mTriedEncode = true;
	return EncodeAttributeReportIB(aArg);
	}

	template <typename T, std::enable_if_t<IsBaseType<T> && IsMatterEnum<T>, bool> = true>
	CHIP_ERROR Encode(const T & aArg)
	{
	using UnderlyingType = std::remove_cv_t<std::remove_reference_t<decltype(to_underlying(aArg))>>;
	static_assert(!std::is_same_v<UnderlyingType, T>, "Encode will call itself recursively");

	CHIP_DM_ENCODING_MAYBE_FAIL_UNKNOWN_ENUM_VALUE(aArg);

	return Encode(to_underlying(aArg));
	}

	template <typename T, std::enable_if_t<!IsBaseType<T>, bool> = true>
	CHIP_ERROR Encode(const T & aArg)
	{
	return Encode(BaseEncodableValue(aArg));
	}

	/**
	* Encode an explicit null value.
	*/
	CHIP_ERROR EncodeNull()
	{
	// Doesn't matter what type Nullable we use here.
	return Encode(DataModel::Nullable<uint8_t>());
	}

	/**
	* Encode an explicit empty list.
	*/
	CHIP_ERROR EncodeEmptyList()
	{
	// Doesn't matter what type List we use here.
	return Encode(DataModel::List<uint8_t>());
	}

	/**
	* aCallback is expected to take a const auto & argument and Encode() on it as many times as needed to encode all the list
	* elements one by one. If any of those Encode() calls returns failure, aCallback must stop encoding and return failure. When
	* all items are encoded aCallback is expected to return success.
	*
	* aCallback may not be called. Consumers must not assume it will be called.
	*
	* When EncodeList returns an error, the consumers must abort the encoding, and return the exact error to the caller.
	*
	* TODO: Can we hold a error state in the AttributeValueEncoder itself?
	*
	* Consumers are allowed to make either one call to EncodeList or one call to Encode to handle a read.
	*
	*/
	template <typename ListGenerator>
	CHIP_ERROR EncodeList(ListGenerator aCallback)
	{
	mTriedEncode = true;
	// Spec 10.5.4.3.1, 10.5.4.6 (Replace a list w/ Multiple IBs)
	// EmptyList acts as the beginning of the whole array type attribute report.
	// An empty list is encoded iff both mCurrentEncodingListIndex and mEncodeState.mCurrentEncodingListIndex are invalid
	// values. After encoding the empty list, mEncodeState.mCurrentEncodingListIndex and mCurrentEncodingListIndex are set to 0.
	ReturnErrorOnFailure(EnsureListStarted());
	CHIP_ERROR err = aCallback(ListEncodeHelper(*this));

	// Even if encoding list items failed, make sure we EnsureListEnded().
	// Since we encode list items atomically, in the case when we just
	// didn't fit the next item we want to make sure our list is properly
	// ended before the reporting engine starts chunking.
	EnsureListEnded();
	if (err == CHIP_NO_ERROR)
	{
	// The Encode procedure finished without any error, clear the state.
	mEncodeState.Reset();
	}
	return err;
	}

	bool TriedEncode() const { return mTriedEncode; }

	const Access::SubjectDescriptor & GetSubjectDescriptor() const { return mSubjectDescriptor; }

	/**
	* The accessing fabric index for this read or subscribe interaction.
	*/
	FabricIndex AccessingFabricIndex() const { return GetSubjectDescriptor().fabricIndex; }

	/**
	* AttributeValueEncoder is a short lived object, and the state is persisted by mEncodeState and restored by constructor.
	*/
	const AttributeEncodeState & GetState() const { return mEncodeState; }

	private:
	// We made EncodeListItem() private, and ListEncoderHelper will expose it by Encode()
	friend class ListEncodeHelper;
	friend class TestOnlyAttributeValueEncoderAccessor;

	// Returns true if the list item should be encoded. If it should, the
	// passed-in TLVWriter will be used to checkpoint the current state of our
	// attribute report list builder.
	bool ShouldEncodeListItem(TLV::TLVWriter & aCheckpoint);

	// Does any cleanup work needed after attempting to encode a list item.
	void PostEncodeListItem(CHIP_ERROR aEncodeStatus, const TLV::TLVWriter & aCheckpoint);

	// EncodeListItem may be given an extra FabricIndex argument as a second
	// arg, or not. Represent that via a parameter pack (which might be
	// empty). In practice, for any given ItemType the extra arg is either there
	// or not, so we don't get more template explosion due to aExtraArgs.
	template <typename ItemType, typename... ExtraArgTypes>
	CHIP_ERROR EncodeListItem(TLV::TLVWriter & aCheckpoint, const ItemType & aItem, ExtraArgTypes &&... aExtraArgs)
	{
	if (!ShouldEncodeListItem(aCheckpoint))
	{
	return CHIP_NO_ERROR;
	}

	CHIP_ERROR err;
	if (mEncodingInitialList)
	{
	// Just encode a single item, with an anonymous tag.
	AttributeReportBuilder builder;
	err = builder.EncodeValue(mAttributeReportIBsBuilder, TLV::AnonymousTag(), aItem,
	std::forward<ExtraArgTypes>(aExtraArgs)...);
	}
	else
	{
	err = EncodeAttributeReportIB(aItem, std::forward<ExtraArgTypes>(aExtraArgs)...);
	}

	PostEncodeListItem(err, aCheckpoint);
	return err;
	}

	/**
	* Builds a single AttributeReportIB in AttributeReportIBs. The caller is
	* responsible for setting up mPath correctly.
	*
	* In particular, when we are encoding a single element in the list, mPath
	* must indicate a null list index to represent an "append" operation.
	* operation.
	*
	* EncodeAttributeReportIB may be given an extra FabricIndex argument as a second
	* arg, or not. Represent that via a parameter pack (which might be
	* empty). In practice, for any given ItemType the extra arg is either
	* there or not, so we don't get more template explosion due to aExtraArgs.
	*/
	template <typename ItemType, typename... ExtraArgTypes>
	CHIP_ERROR EncodeAttributeReportIB(const ItemType & aItem, ExtraArgTypes &&... aExtraArgs)
	{
	AttributeReportBuilder builder;
	ReturnErrorOnFailure(builder.PrepareAttribute(mAttributeReportIBsBuilder, mPath, mDataVersion));
	ReturnErrorOnFailure(builder.EncodeValue(mAttributeReportIBsBuilder, TLV::ContextTag(AttributeDataIB::Tag::kData), aItem,
	std::forward<ExtraArgTypes>(aExtraArgs)...));

	return builder.FinishAttribute(mAttributeReportIBsBuilder);
	}

	/**
	* EnsureListStarted sets our mCurrentEncodingListIndex to 0, and:
	*
	* * If we are just starting the list, gets us ready to encode list items.
	*
	* * If we are continuing a chunked list, guarantees that mPath.mListOp is
	* AppendItem after it returns.
	*/
	CHIP_ERROR EnsureListStarted();

	/**
	* EnsureListEnded writes out the end of the list and our attribute data IB,
	* if we were encoding our initial list
	*/
	void EnsureListEnded();

	AttributeReportIBs::Builder & mAttributeReportIBsBuilder;
	const Access::SubjectDescriptor mSubjectDescriptor;
	ConcreteDataAttributePath mPath;
	DataVersion mDataVersion;
	bool mTriedEncode = false;
	bool mIsFabricFiltered = false;
	// mEncodingInitialList is true if we're encoding a list and we have not
	// started chunking it yet, so we're encoding a single attribute report IB
	// for the whole list, not one per item.
	bool mEncodingInitialList = false;
	// mEncodedAtLeastOneListItem becomes true once we successfully encode a list item.
	bool mEncodedAtLeastOneListItem = false;
	ListIndex mCurrentEncodingListIndex = kInvalidListIndex;
	AttributeEncodeState mEncodeState;
	};

	} // namespace app
	} // namespace chip