透過集合功能整理內容 你可以依據偏好儲存及分類內容。

nl::編織::TLV::TLVUpdater

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

提供統一的讀取者/寫入工具介面,供編輯/新增/刪除 TLV 編碼中的元素。

摘要

TLVUpdaterTLVreaderTLVWriter 物件的聯集,提供在編碼中編輯/刪除資料的介面方法,以及為 TLV 編碼新增元素。TLVUpdater 物件基本上可當做兩個遊標,一個用於讀取現有編碼,另一個用於寫入 (現有資料複製或寫入新資料)。

基本上,TLVUpdater 物件的運作方式是 TLVReaderTLVWriter 的聯集。TLVUpdater 方法的含義在 TLVReader/TLVWriter 中類似且類似。如有語意的差異,系統會在 WeaveTLVUpdater.cpp 的函式註解一節中清楚記錄差異。

關於 TLVUpdater 和 # PutBytes() 和 PutString() 方法的一大重點是,它可以使編碼處於損毀狀態,而僅在溢位發生時寫入元素標頭。應用程式可以呼叫 GetRemainingFreeLength() 來確認「有」足夠可用空間可寫入編碼。請注意,GetRemainingFreeLength() 僅指出可用免費位元組,應用程式無法得知所寫入的編碼資料長度。如果溢位,則 PutBytes() 和 PutString() 都會向呼叫端傳回 WEAVE_ERROR_BUFFER_TOO_SMALL。

另外請注意,Next() 方法會超載以略過目前元素,同時將內部讀取器推向下一個元素。由於略過已編碼的編碼元素需要變更內部寫入器的可用空間空間變數,以納入新的釋出空間 (透過略過提供),因此應用程式會在 Get() 方法之後,呼叫 Next(),其值不應寫入 (相當於略過目前的元素)。

公用函式

CopyElement(TLVReader & reader)
CopyElement(uint64_t tag, TLVReader & reader)
DupBytes(uint8_t *& buf, uint32_t & dataLen)
DupString(char *& buf)
EndContainer(TLVType outerContainerType)
EnterContainer(TLVType & outerContainerType)
準備 TLVUpdater 物件,以便讀取容器元素。
ExitContainer(TLVType outerContainerType)
完成 TLV 容器元素的讀取作業,並將輸出 TLV 元素的結尾編碼為輸出 TLV
Finalize(void)
Get(bool & v)
Get(int8_t & v)
Get(int16_t & v)
Get(int32_t & v)
Get(int64_t & v)
Get(uint8_t & v)
Get(uint16_t & v)
Get(uint32_t & v)
Get(uint64_t & v)
Get(float & v)
Get(double & v)
GetBytes(uint8_t *buf, uint32_t bufSize)
GetContainerType(void) const
GetDataPtr(const uint8_t *& data)
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)
GetTag(void) const
uint64_t
GetType(void) const
Init(uint8_t *buf, uint32_t dataLen, uint32_t maxLen)
初始化 TLVUpdater 物件以編輯單一輸入緩衝區。
Init(TLVReader & aReader, uint32_t freeLen)
使用 TLVReader 初始化 TLVUpdater 物件。
Move(void)
將目前的元素複製到輸入 TLV,以便輸出 TLV
MoveUntilEnd(void)
void
TLVUpdater 和 #39; 中的目前讀取點移至輸入 TLV 的緩衝區,直到結束輸出。
Next(void)
略過目前的元素,並將 TLVUpdater 物件推進輸入 TLV 中的下一個元素。
Put(uint64_t tag, int8_t v)
Put(uint64_t tag, int16_t v)
Put(uint64_t tag, int32_t v)
Put(uint64_t tag, int64_t v)
Put(uint64_t tag, uint8_t v)
Put(uint64_t tag, uint16_t v)
Put(uint64_t tag, uint32_t v)
Put(uint64_t tag, uint64_t v)
Put(uint64_t tag, int8_t v, bool preserveSize)
Put(uint64_t tag, int16_t v, bool preserveSize)
Put(uint64_t tag, int32_t v, bool preserveSize)
Put(uint64_t tag, int64_t v, bool preserveSize)
Put(uint64_t tag, uint8_t v, bool preserveSize)
Put(uint64_t tag, uint16_t v, bool preserveSize)
Put(uint64_t tag, uint32_t v, bool preserveSize)
Put(uint64_t tag, uint64_t v, bool preserveSize)
Put(uint64_t tag, float v)
Put(uint64_t tag, double v)
PutBoolean(uint64_t tag, bool v)
PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)
PutNull(uint64_t tag)
PutString(uint64_t tag, const char *buf)
PutString(uint64_t tag, const char *buf, uint32_t len)
SetImplicitProfileId(uint32_t profileId)
void
設定 TLVUpdater 物件的隱式設定檔 ID。
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
VerifyEndOfContainer(void)

公用函式

複製元素

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

複製元素

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

DupBytes

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

DupString

WEAVE_ERROR DupString(
  char *& buf
)

結束容器

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

準備 TLVUpdater 物件,以便讀取容器元素。

也會在輸出內容 TLV 中對容器物件的開頭進行編碼。

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

呼叫 EnterContainer() 時,TLVUpdater 至 #39; 的讀取器必須放置在容器元素上。這種方法會將引數視為 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 遭到截斷。

詳情
參數
[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
)

取得容器類型

TLVType GetContainerType(
  void
) const 

取得資料

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

取得影響設定檔 ID

uint32_t GetImplicitProfileId(
  void
)

GetLength

uint32_t GetLength(
  void
) const 

GetLengthRead

uint32_t GetLengthRead(
  void
) const 

變成長度

uint32_t GetLengthWritten(
  void
)

讀取閱讀器

void GetReader(
  TLVReader & containerReader
)

取得免費長度

uint32_t GetRemainingFreeLength(
  void
)

取得長度

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 

初始

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
如果緩衝區太小。

初始

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

使用 TLVReader 初始化 TLVUpdater 物件。

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

請注意,如果 TLVreader 已位於 "element" 的位置,則該元素會先補回該元素的開頭。另外也請注意,這項移除功能適用於容器元素,例如,如果 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 和 #39; 閱讀器所在的目前元素複製到 TLVUpdater 和 #39; 的寫入者。應用程式應呼叫 Next(),並在呼叫這個方法之前,將 TLVUpdater 和 #39; 讀取者放在元素上。如同 TLVReader::Next() 方法,如果讀取者在呼叫時位於容器元素中,容器的所有成員都會複製。如果讀取器未找到任何元素,則呼叫這個方法不會有任何變更。

詳情
傳回值
WEAVE_NO_ERROR
如果 TLVUpdater 讀取者已成功定位到新元素,
WEAVE_END_OF_TLV
如果 TLVUpdater 和 #39; 的閱讀器指向容器結尾。
WEAVE_ERROR_INVALID_TLV_ELEMENT
如果 TLVIpdater' 閱讀器不在有效的 TLV 元素上。
other
傳回 TLVReader::Skip() 方法傳回的其他錯誤代碼。

移至結束時間

void MoveUntilEnd(
  void
)

TLVUpdater 和 #39; 中的目前讀取點移至輸入 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。要求更新工具對新元素進行編碼時,如果與新元素相關聯的標記設定檔 ID 與 profileId 的值相符,

詳情
參數
[in] profileId
應以隱含形式編碼的代碼設定檔 ID。

啟動容器

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

驗證結束容器

WEAVE_ERROR VerifyEndOfContainer(
  void
)