本頁面由 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() 方法之後，對更新工具呼叫 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 元素的結尾進行編碼。

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

ExitContainer() 傳回時，TLVUpdater 讀取器會緊鄰輸入 TLV 中容器後面的元素之前。從這個時間點，應用程式可以呼叫 Next() 以前往任何剩餘的元素。

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

注意：呼叫 ExitContainer() 不會復原對 EnterContainer() 和 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 已定位在元素上，它會先備份至該元素的開頭。另請注意，此輪詢和容器元素可正常運作，也就是說，如果 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 或平台錯誤代碼。

最佳做法，

WEAVE_ERROR 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
)

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。當更新工具要求為新元素編碼時，如果與新元素相關聯的標記設定檔 ID 與 profileId 的值相符，更新器就會以隱含形式將標記編碼，同時在過程中省略設定檔 ID。

詳細說明

參數

[in] profileId

代碼的設定檔 ID，應以隱含格式編碼。

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)