本頁面由 Cloud Translation API 翻譯而成。

nl::Weave::TLV::TLVUpdater

#include <src/lib/core/WeaveTLV.h>

提供整合的 Reader/Writer 介面，用於編輯/新增/刪除 TLV 編碼的元素。

摘要

TLVUpdater 是 TLVReader 和 TLVWriter 物件的聯集，可提供在編碼中編輯/刪除資料的介面方法，以及在 TLV 編碼中加入新元素。TLVUpdater 物件的作用類似兩個遊標，一個用於讀取現有編碼，另一個則用於寫入 (用於複製現有資料或寫入新資料)。

從語意的角度來看，TLVUpdater 物件函式就如同 TLVReader 和 TLVWriter 的聯集。TLVUpdater 方法的含義與 TLVReader/TLVWriter 中的名稱相似。如果語意有所差異，請參閱 WeaveTLVUpdater.cpp 中函式的註解部分，當中清楚說明差異。

關於 TLVUpdater 的 PutBytes() 和 PutString() 方法，還有一個特別要注意的是，它可以將編碼保留在損毀狀態，僅在溢位發生時寫入元素標頭。應用程式可呼叫 GetRemainingFreeLength() 以確保「大約」有足夠的可用空間可寫入編碼。請注意，GetRemainingFreeLength() 只會告知您可用的免費位元組，而且應用程式無法得知寫入的資料長度。如果發生溢位，PutBytes() 和 PutString() 都會將 WEAVE_ERROR_BUFFER_TOO_SMALL 傳回給呼叫端。

另請注意，Next() 方法會超載，以便略過目前的元素，同時讓內部讀取器前進到下一個元素。由於略過已編碼的元素需要變更內部寫入者的可用空間狀態變數，以考量新的可用空間 (可透過略過可用)，因此應用程式應在 Get() 方法之後，對不想要寫回的值 (相當於略過目前元素) 的 Updater 呼叫 Next()。

，瞭解如何調查及移除這項存取權。

公開函式
`CopyElement(TLVReader & reader)`	`WEAVE_ERROR`
`CopyElement(uint64_t tag, TLVReader & reader)`	`WEAVE_ERROR`
`DupBytes(uint8_t *& buf, uint32_t & dataLen)`	`WEAVE_ERROR`
`DupString(char *& buf)`	`WEAVE_ERROR`
`EndContainer(TLVType outerContainerType)`	`WEAVE_ERROR`
`EnterContainer(TLVType & outerContainerType)`	`WEAVE_ERROR` 準備用於讀取容器元素的 TLVUpdater 物件。
`ExitContainer(TLVType outerContainerType)`	`WEAVE_ERROR` 完成 TLV 容器元素的讀取作業，並對輸出 TLV 中的 TLV 元素進行編碼。
`Finalize(void)`	`WEAVE_ERROR`
`Get(bool & v)`	`WEAVE_ERROR`
`Get(int8_t & v)`	`WEAVE_ERROR`
`Get(int16_t & v)`	`WEAVE_ERROR`
`Get(int32_t & v)`	`WEAVE_ERROR`
`Get(int64_t & v)`	`WEAVE_ERROR`
`Get(uint8_t & v)`	`WEAVE_ERROR`
`Get(uint16_t & v)`	`WEAVE_ERROR`
`Get(uint32_t & v)`	`WEAVE_ERROR`
`Get(uint64_t & v)`	`WEAVE_ERROR`
`Get(float & v)`	`WEAVE_ERROR`
`Get(double & v)`	`WEAVE_ERROR`
`GetBytes(uint8_t *buf, uint32_t bufSize)`	`WEAVE_ERROR`
`GetContainerType(void) const`	`TLVType`
`GetDataPtr(const uint8_t *& data)`	`WEAVE_ERROR`
`GetImplicitProfileId(void)`	`uint32_t`
`GetLength(void) const`	`uint32_t`
`GetLengthRead(void) const`	`uint32_t`
`GetLengthWritten(void)`	`uint32_t`
`GetReader(TLVReader & containerReader)`	`void`
`GetRemainingFreeLength(void)`	`uint32_t`
`GetRemainingLength(void) const`	`uint32_t`
`GetString(char *buf, uint32_t bufSize)`	`WEAVE_ERROR`
`GetTag(void) const`	`uint64_t`
`GetType(void) const`	`TLVType`
`Init(uint8_t *buf, uint32_t dataLen, uint32_t maxLen)`	`WEAVE_ERROR` 初始化 TLVUpdater 物件即可編輯單一輸入緩衝區。
`Init(TLVReader & aReader, uint32_t freeLen)`	`WEAVE_ERROR` 使用 TLVReader 初始化 TLVUpdater 物件。
`Move(void)`	`WEAVE_ERROR` 將目前的元素從輸入 TLV 複製到輸出 TLV。
`MoveUntilEnd(void)`	`void` 將 TLVUpdater 目前讀取點到輸入 TLV 緩衝區之間的所有內容移至輸出內容。
`Next(void)`	`WEAVE_ERROR` 略過目前的元素，並將 TLVUpdater 物件前進至輸入 TLV 中的下一個元素。
`Put(uint64_t tag, int8_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint8_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint64_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int8_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint8_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint64_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, float v)`	`WEAVE_ERROR`
`Put(uint64_t tag, double v)`	`WEAVE_ERROR`
`PutBoolean(uint64_t tag, bool v)`	`WEAVE_ERROR`
`PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)`	`WEAVE_ERROR`
`PutNull(uint64_t tag)`	`WEAVE_ERROR`
`PutString(uint64_t tag, const char *buf)`	`WEAVE_ERROR`
`PutString(uint64_t tag, const char *buf, uint32_t len)`	`WEAVE_ERROR`
`SetImplicitProfileId(uint32_t profileId)`	`void` 設定 TLVUpdater 物件的隱含設定檔 ID。
`StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)`	`WEAVE_ERROR`
`VerifyEndOfContainer(void)`	`WEAVE_ERROR`

公開函式

CopyElement

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

CopyElement

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

DupString

WEAVE_ERROR DupString(
  char *& buf
)

EndContainer

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

準備用於讀取容器元素的 TLVUpdater 物件。

也會對輸出 TLV 中的容器物件開始編碼。

EnterContainer() 方法會準備目前的 TLVUpdater 物件，以便開始讀取 TLV 容器 (結構、陣列或路徑) 的成員元素。每次呼叫 EnterContainer() 應用程式時，都必須發出對應的 ExitContainer() 呼叫。

呼叫 EnterContainer() 時，TLVUpdater 的讀取器必須位在容器元素上。此方法會將 TLVType 值的參照做為引數，以便在更新容器讀取容器時儲存更新工具的內容。

EnterContainer() 方法傳回時，更新工具的位置緊接在容器的第一個成員「之前」。重複呼叫 Next() 會將更新工具從集合成員前進，直到抵達結束為止，此時更新器將傳回 WEAVE_END_OF_TLV。

應用程式讀取完容器後，可以透過呼叫 ExitContainer() 方法繼續讀取容器之後的元素。

詳細資料

參數

[out] outerContainerType

要接收更新工具背景資訊的 TLVType 參照。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果 TLVUpdater 讀取器未位於容器元素上。
`other`	TLVWriter::StartContainer() 或 TLVReader::EnterContainer() 傳回的任何其他 Weave 或平台錯誤代碼。

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

完成 TLV 容器元素的讀取作業，並對輸出 TLV 中的 TLV 元素進行編碼。

ExitContainer() 方法會在呼叫 EnterContainer() 後還原 TLVUpdater 物件的狀態。每次呼叫 EnterContainer() 應用程式時，都必須對 ExitContainer() 應用程式發出對應的呼叫，傳遞 EnterContainer() 方法傳回的結構定義值。

ExitContainer() 傳回值時，TLVUpdater 讀取器的位置會立即位於輸入內容 TLV 中容器後方的第一個元素之前。此時，應用程式可以呼叫 Next()，前進至任何剩餘的元素。

呼叫 EnterContainer() 後，無論基礎容器中的所有元素是否已讀取，應用程式隨時都可在更新器上呼叫 ExitContainer()。另外請注意，如果在讀取容器中的所有元素之前呼叫 ExitContainer()，會導致更新的容器在輸出 TLV 中遭到截斷。

注意：在呼叫 EnterContainer() 和 ExitContainer() 之間，對更新器設定所做的任何變更，不會因呼叫 ExitContainer() 而復原。舉例來說，離開容器時，對隱性設定檔 ID (ImplicitProfileId) 所做的變更並不會撤銷。因此，應用程式有責任適時調整設定。

詳細資料

參數

[in] outerContainerType

EnterContainer() 方法傳回的 TLVType 值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果更新工具遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果更新程式在無效的情況下遇到 TLV 標記。
`other`	TLVWriter::EndContainer() 或 TLVReader::ExitContainer() 傳回的任何其他 Weave 或平台錯誤代碼。

完成

WEAVE_ERROR Finalize(
  void
)

取得

WEAVE_ERROR Get(
  bool & v
)

取得

WEAVE_ERROR Get(
  int8_t & v
)

取得

WEAVE_ERROR Get(
  int16_t & v
)

取得

WEAVE_ERROR Get(
  int32_t & v
)

取得

WEAVE_ERROR Get(
  int64_t & v
)

取得

WEAVE_ERROR Get(
  uint8_t & v
)

取得

WEAVE_ERROR Get(
  uint16_t & v
)

取得

WEAVE_ERROR Get(
  uint32_t & v
)

取得

WEAVE_ERROR Get(
  uint64_t & v
)

取得

WEAVE_ERROR Get(
  float & v
)

取得

WEAVE_ERROR Get(
  double & v
)

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

GetContainerType

TLVType GetContainerType(
  void
) const

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

GetImplicitProfileId

uint32_t GetImplicitProfileId(
  void
)

GetLength

uint32_t GetLength(
  void
) const

GetLengthRead

uint32_t GetLengthRead(
  void
) const

GetLengthWritten

uint32_t GetLengthWritten(
  void
)

GetReader

void GetReader(
  TLVReader & containerReader
)

GetRemainingFreeLength

uint32_t GetRemainingFreeLength(
  void
)

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

GetTag

uint64_t GetTag(
  void
) const

GetType

TLVType GetType(
  void
) const

Init

WEAVE_ERROR Init(
  uint8_t *buf,
  uint32_t dataLen,
  uint32_t maxLen
)

初始化 TLVUpdater 物件即可編輯單一輸入緩衝區。

呼叫這個方法時，緩衝區中的 TLV 資料會移至緩衝區的末端，並在這個重新放置的緩衝區上初始化私人 TLVReader 物件。私人 TLVWriter 物件也會在一開始可用的可用空間初始化。應用程式可以使用 TLVUpdater 物件剖析 TLV 資料並修改/刪除現有元素，或是在編碼中新增元素。

詳細資料

參數

`[in] buf`	指向內含待編輯 TLV 資料的緩衝區。
`[in] dataLen`	緩衝區中的 TLV 資料長度。
`[in] maxLen`	緩衝區的總長度。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INVALID_ARGUMENT`	如果緩衝區位址無效，
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果緩衝區太小。

Init

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

使用 TLVReader 初始化 TLVUpdater 物件。

呼叫此方法時，TLVReader 所指向的緩衝區中的 TLV 資料會從目前的讀取點移至緩衝區的結尾。新的私人 TLVReader 物件初始化為從這個新位置讀取，新的私人 TLVWriter 物件會初始化，以便寫入釋出的緩衝區空間。

請注意，如果 TLVReader 已定位為「on」元素就會先備份至該元素的開頭。另請注意，關閉關閉功能對容器元素效果不錯，意即如果 TLVReader 已用於呼叫 EnterContainer()，則沒有可輪詢的項目。但如果 TLVReader 已定位在容器元素上，且尚未呼叫 EnterContainer()，則 TLVReader 物件會備份至容器標頭的開頭。

輸入 TLVReader 物件會在傳回前刪除，且應用程式不得在傳回時使用相同的輸入值。

詳細資料

參數

`[in,out] aReader`	對要在傳回前刪除的 TLVReader 物件參照。
`[in] freeLen`	預先編碼資料緩衝區中可用的可用空間長度 (以位元組為單位)。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INVALID_ARGUMENT`	如果緩衝區位址無效，
`WEAVE_ERROR_NOT_IMPLEMENTED`	如果讀取器已在緩衝區鏈結中初始化。

移動

WEAVE_ERROR Move(
  void
)

將目前的元素從輸入 TLV 複製到輸出 TLV。

Move() 方法會將 TLVUpdater 讀取器所在的元素複製到 TLVUpdater 的寫入者中。應用程式應在呼叫這個方法前呼叫 Next()，並在元素上放置 TLVUpdater 的讀取器。如同 TLVReader::Next() 方法，如果讀取器在呼叫期間的容器元素上，容器的所有成員都會複製。如果讀取器未移至任何元素，則呼叫此方法不會有任何變更。

詳細資料

傳回值

`WEAVE_NO_ERROR`	TLVUpdater 讀取器成功放置在新元素上。
`WEAVE_END_OF_TLV`	如果 TLVUpdater 讀取器指向容器結尾。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果 TLVIpdater 的讀取器位在有效的 TLV 元素上。
`other`	傳回 TLVReader::Skip() 方法傳回的其他錯誤代碼。

MoveUntilEnd

void MoveUntilEnd(
  void
)

將 TLVUpdater 目前讀取點到輸入 TLV 緩衝區之間的所有內容移至輸出內容。

這個方法支援將所有內容從 TLVUpdater 的目前讀取點，直到讀取器緩衝區的結尾為止，移至 TLVUpdater 的寫入者。

繼續

WEAVE_ERROR Next(
  void
)

略過目前的元素，並將 TLVUpdater 物件前進至輸入 TLV 中的下一個元素。

Next() 方法會略過輸入 TLV 中的目前元素，並將 TLVUpdater 讀取器前進至位於相同隔離結構定義中的下一個元素。尤其是如果讀取器的位置位於 TLV 編碼的最外層，則呼叫 Next() 會將其導向下一個、最大的元素。如果讀取器位於 TLV 容器元素 (結構、陣列或路徑) 中，則呼叫 Next() 會將其導向容器的下一個成員元素。

由於 Next() 會將讀者的動作限制在目前的遏制環境下，因此當讀取器位於容器元素上時呼叫 Next()，會「移動」容器並略過其成員元素 (以及任何巢狀容器的成員)，直到它到達容器之後的第一個元素為止。

如果特定容器內容中沒有其他元素，Next() 方法就會傳回 WEAVE_END_OF_TLV 錯誤，且讀取器的位置會維持不變。

詳細資料

傳回值

`WEAVE_NO_ERROR`	TLVUpdater 讀取器成功放置在新元素上。
`other`	傳回 TLVReader::Skip() 和 TLVReader::Next() 方法傳回的 Weave 或平台錯誤代碼。

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  double v
)

PutBoolean

WEAVE_ERROR PutBoolean(
  uint64_t tag,
  bool v
)

PutBytes

WEAVE_ERROR PutBytes(
  uint64_t tag,
  const uint8_t *buf,
  uint32_t len
)

PutNull

WEAVE_ERROR PutNull(
  uint64_t tag
)

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf
)

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf,
  uint32_t len
)

SetImplicitProfileId

void SetImplicitProfileId(
  uint32_t profileId
)

設定 TLVUpdater 物件的隱含設定檔 ID。

這個方法會設定 TLVUpdater 物件的隱含設定檔 ID。當系統要求 Updater 對新元素進行編碼時，如果與新元素相關聯的標記資料 ID 與 profileId 的值相符，則更新工具會以隱含形式將標記編碼，因此在過程中省略設定檔 ID。

詳細資料

參數

[in] profileId

應以隱含格式編碼的標記設定檔 ID。

StartContainer

WEAVE_ERROR StartContainer(
  uint64_t tag,
  TLVType containerType,
  TLVType & outerContainerType
)

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)