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

nl::Weave::TLV::TLVReader

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

針對以 Weave TLV 格式編碼的資料，提供記憶體效率剖析器。

摘要

TLVReader 為 Weave TLV 資料實作正向式的「pull-style」剖析器。TLVReader 物件會做為遊標運作，可用於疊代多個 TLV 元素並解讀其內容。放置在元素上時，應用程式可以呼叫讀取器的 Get() 方法，查詢目前元素的類型和標記，並擷取任何相關聯的值。讀取器的 Next() 方法用於從元素前往元素。

TLVReader 物件一律位於 TLV 元素之前、之後或之後。初次初始化時，TLVReader 會位於編碼的第一個元素之前。如要開始朗讀，應用程式必須對 Next() 方法發出初始呼叫，才能將讀取器置於第一個元素。容器元素遇到結構時，可以使用 OpenContainer() 或 EnterContainer() 方法進行陣列內容疊代。

當讀取器到達 TLV 編碼的結尾或容器中的最後一個元素時，它會從 Next() 方法傳回 WEAVE_END_OF_TLV 錯誤，以通知應用程式。在重新初始化或目前容器 (透過 CloseContainer() / ExitContainer()) 退出 WEAVE_END_OF_TLV 之前，讀取器會繼續傳回 WEAVE_END_OF_TLV。

TLVReader 物件可以直接從固定的輸入緩衝區或一或多個 PacketBuffer 的鏈結剖析資料。此外，應用程式也可以提供 GetNextBuffer 函式，從任意來源 (例如通訊埠或序列埠。

繼承

直接已知的子類別：
nl::Weave::Profiles::DataManagement_Current::CircularEventReader
nl::Weave::TLV::CircularTLVReader

公開類型
`GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen)`	WEAVE_ERROR() `WEAVE_ERROR(` 這個函式可用來擷取要剖析的其他 TLV 資料。

公開屬性
`AppData`	`void *` 可用於應用程式特定資料的指標欄位。
`GetNextBuffer`	`GetNextBufferFunct` 可產生 TLVReader 物件輸入資料的函式指標。
`ImplicitProfileId`	`uint32_t` 設定檔 ID 要用於以隱含形式編碼的個人資料標記。

受保護的屬性
`mBufEnd`	`const uint8_t *`
`mBufHandle`	`uintptr_t`
`mContainerType`	`TLVType`
`mControlByte`	`uint16_t`
`mElemLenOrVal`	`uint64_t`
`mElemTag`	`uint64_t`
`mLenRead`	`uint32_t`
`mMaxLen`	`uint32_t`
`mReadPoint`	`const uint8_t *`

公開函式
`CloseContainer(TLVReader & containerReader)`	`WEAVE_ERROR` 在呼叫 OpenContainer() 後，完成 TLV 容器讀取。
`DupBytes(uint8_t *& buf, uint32_t & dataLen)`	`WEAVE_ERROR` 分配並傳回包含目前位元組或 UTF8 字串值的緩衝區。
`DupString(char *& buf)`	`WEAVE_ERROR` 分配並傳回含有目前位元組或 UTF8 字串之空值結束值的緩衝區。
`EnterContainer(TLVType & outerContainerType)`	`WEAVE_ERROR` 準備用來讀取 TLV 容器元素成員的 TLVReader 物件。
`ExitContainer(TLVType outerContainerType)`	`WEAVE_ERROR` 完成 TLV 容器讀取作業，並準備 TLVReader 物件在容器之後讀取元素。
`Get(bool & v)`	`WEAVE_ERROR` 取得目前元素的值做為布林值類型。
`Get(int8_t & v)`	`WEAVE_ERROR` 取得目前元素的值，為 8 位元帶正負號整數。
`Get(int16_t & v)`	`WEAVE_ERROR` 以 16 位元帶正負號整數取得目前元素的值。
`Get(int32_t & v)`	`WEAVE_ERROR` 以 32 位元帶正負號整數取得目前元素的值。
`Get(int64_t & v)`	`WEAVE_ERROR` 以 64 位元帶正負號整數取得目前元素的值。
`Get(uint8_t & v)`	`WEAVE_ERROR` 以 8 位元無正負號整數取得目前元素的值。
`Get(uint16_t & v)`	`WEAVE_ERROR` 以 16 位元無正負號整數取得目前元素的值。
`Get(uint32_t & v)`	`WEAVE_ERROR` 以 32 位元無正負號整數取得目前元素的值。
`Get(uint64_t & v)`	`WEAVE_ERROR` 以 64 位元無正負號整數取得目前元素的值。
`Get(float & v)`	`WEAVE_ERROR`
`Get(double & v)`	`WEAVE_ERROR` 取得目前元素的值，做為雙精度浮點數。
`GetBufHandle(void) const`	`uintptr_t`
`GetBytes(uint8_t *buf, uint32_t bufSize)`	`WEAVE_ERROR` 取得目前位元組或 UTF8 字串元素的值。
`GetContainerType(void) const`	`TLVType` 傳回 TLVReader 目前正在讀取的容器類型。
`GetControlByte(void) const`	`uint16_t` 傳回與目前 TLV 元素相關聯的控制位元組。
`GetDataPtr(const uint8_t *& data)`	`WEAVE_ERROR` 取得 TLV 位元組或 UTF8 字串元素的初始編碼位元組指標。
`GetLength(void) const`	`uint32_t` 傳回與目前 TLV 元素相關聯的資料長度。
`GetLengthRead(void) const`	`uint32_t` 傳回讀取器初始化後讀取的位元組總數。
`GetReadPoint(void) const`	`const uint8_t *` 取得與讀取器目前位置相對應的基礎輸入緩衝區的點。
`GetRemainingLength(void) const`	`uint32_t` 傳回在達到讀取長度上限前可讀取的位元組總數。
`GetString(char *buf, uint32_t bufSize)`	`WEAVE_ERROR` 取得目前位元組或 UTF8 字串元素的值，做為空值終止字串。
`GetTag(void) const`	`uint64_t` 傳回與目前 TLV 元素相關聯的標記。
`GetType(void) const`	`TLVType` 傳回目前 TLV 元素的類型。
`Init(const TLVReader & aReader)`	`void` 初始化另一個 TLVReader 物件的 TLVReader 物件。
`Init(const uint8_t *data, uint32_t dataLen)`	`void` 初始化要讀取單一輸入緩衝區的 TLVReader 物件。
`Init(PacketBuffer *buf, uint32_t maxLen)`	`void` 初始化要從單一 PacketBuffer 讀取的 TLVReader 物件。
`Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)`	`void` 初始化 TLVReader 物件來讀取一或多個 PacketBuffer。
`Next(void)`	`WEAVE_ERROR` 將 TLVReader 物件導向下一個要讀取的 TLV 元素。
`Next(TLVType expectedType, uint64_t expectedTag)`	`WEAVE_ERROR` 將 TLVReader 物件移至下一個要讀取的 TLV 元素，宣告新元素的類型和標記。
`OpenContainer(TLVReader & containerReader)`	`WEAVE_ERROR` 初始化新的 TLVReader 物件來讀取 TLV 容器元素的成員。
`Skip(void)`	`WEAVE_ERROR` 將 TLVReader 物件移至目前的 TLV 元素之後。
`VerifyEndOfContainer(void)`	`WEAVE_ERROR` 驗證 TVLReader 物件是否位於 TLV 容器的結尾。

受保護的函式
`ClearElementState(void)`	`void` 清除 TLVReader 狀態。
`ElementType(void) const`	`TLVElementType` 這是私人方法，會從 mControlByte 傳回 TLVElementType。
`EnsureData(WEAVE_ERROR noDataErr)`	`WEAVE_ERROR`
`GetElementHeadLength(uint8_t & elemHeadBytes) const`	`WEAVE_ERROR` 這是一種私人方法，用來計算 TLV 元素頭部的長度。
`IsContainerOpen(void) const`	`bool`
`ReadData(uint8_t *buf, uint32_t len)`	`WEAVE_ERROR`
`ReadElement(void)`	`WEAVE_ERROR`
`ReadTag(TLVTagControl tagControl, const uint8_t *& p)`	`uint64_t`
`SetContainerOpen(bool aContainerOpen)`	`void`
`SkipData(void)`	`WEAVE_ERROR` 透過不使用目的地緩衝區的方式讀取，略過目前 TLV 中包含的任何資料。
`SkipToEndOfContainer(void)`	`WEAVE_ERROR`
`VerifyElement(void)`	`WEAVE_ERROR`

受保護的靜態函式
`FailGetNextBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)`	`WEAVE_ERROR`
`GetNextPacketBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)`	`WEAVE_ERROR`

公開類型

GetNextBufferFunct

WEAVE_ERROR(* GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen)

這個函式可用來擷取要剖析的其他 TLV 資料。

這個類型的函式可用來將輸入資料提供給 TLVReader。呼叫該函式時，函式預期會產生額外資料，供讀取器剖析或告知讀取器已無其他可用資料。

詳細資料

參數

`[in] reader`	參照要求輸入資料的 TLVReader 物件。
`[in,out] bufHandle`	這是對 uintptr_t 值的參照，可供函式在呼叫之間儲存結構定義資料。這個值會在第一次呼叫前初始化為 0。
`[in,out] bufStart`	資料點的參照。在函式進入時，`bufStart` 會指向讀取器耗用的最後一個 TLV 資料位元組以外的一個位元組。結束時，bufStart 預期會指向要剖析的新 TLV 資料第一個位元組。新指標值可以與先前使用的資料位於相同的緩衝區中，也可以指向一個全新的緩衝區。
`[out] bufLen`	這是對無正負號整數的參照，函式必須設為要傳回的 TLV 資料位元組數量。如果輸入 TLV 資料結尾已用盡，函式應將這個值設為 0。

傳回值

`WEAVE_NO_ERROR`	如果函式成功產生更多 TLV 資料，或輸入資料的結尾已到達 (在此案例中，`bufLen`應設為 0)。
`other`	其他 Weave 或平台專屬錯誤代碼，表示發生錯誤，導致函式無法產生要求的資料。

公開屬性

AppData

void * AppData

可用於應用程式特定資料的指標欄位。

GetNextBuffer

GetNextBufferFunct GetNextBuffer

可產生 TLVReader 物件輸入資料的函式指標。

如果設為 NULL (預設值)，讀取器會假設沒有其他可用的輸入資料。

您可以隨時透過應用程式設定 GetNextBuffer，但通常會在讀取器初始化時設定。

如要進一步瞭解如何實作 GetNextBuffer 函式，請參閱 GetNextBufferFunct 類型定義。

ImplicitProfileId

uint32_t ImplicitProfileId

設定檔 ID 要用於以隱含形式編碼的個人資料標記。

讀取器碰到以隱含形式編碼的個人資料專屬標記時，會使用 ImplicitProfileId 屬性的值做為該標記的假設設定檔 ID。

ImplicitProfileId 屬性的預設設定是 kProfileIdNotSpecified。解碼包含隱含編碼標記的 TLV 時，應用程式必須先設定 ImplicitProfileId，才能讀取具有這類標記的任何 TLV 元素。適當的個人資料 ID 通常取決於系統朗讀的應用程式或通訊協定。

如果在 ImplicitProfileId 設為 kProfileIdNotSpecified 時遇到隱含編碼的標記，讀取器會傳回 WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG 錯誤。

受保護的屬性

mBufEnd

const uint8_t * mBufEnd

mBufHandle

uintptr_t mBufHandle

mContainerType

TLVType mContainerType

mControlByte

uint16_t mControlByte

mElemLenOrVal

uint64_t mElemLenOrVal

mElemTag

uint64_t mElemTag

mLenRead

uint32_t mLenRead

mMaxLen

uint32_t mMaxLen

mReadPoint

const uint8_t * mReadPoint

公開函式

CloseContainer

WEAVE_ERROR CloseContainer(
  TLVReader & containerReader
)

在呼叫 OpenContainer() 後，完成 TLV 容器讀取。

CloseContainer() 方法會在呼叫 OpenContainer() 後，還原父項 TLVReader 物件的狀態。每次呼叫 OpenContainer() 應用程式時，都必須對 CloseContainer() 應用程式發出對應的呼叫，並將同一個容器讀取器的參照傳遞至這兩個方法。

CloseContainer() 傳回時，父項讀取器會位於容器後面的第一個元素之前。此時，應用程式可以利用 Next() 方法，前往任何剩餘元素。

無論基礎容器中的所有元素是否已讀取，應用程式隨時都可在父項讀取器上呼叫 CloseContainer()。呼叫 CloseContainer() 後，應用程式應將容器讀取器視為「de-initialized」且不需要重新初始化，即可進一步使用。

詳細資料

參數

[in] containerReader

提供給 OpenContainer() 方法的 TLVReader 物件參照。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果讀取器上尚未呼叫 OpenContainer()，或是容器讀取器與傳遞至 OpenContainer() 方法的容器不相符，則進行了。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果讀取器在無效環境中遇到 TLV 標記。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

DupBytes

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

分配並傳回包含目前位元組或 UTF8 字串值的緩衝區。

這個方法會為建立緩衝區，並傳回目前位置的位元組或 UTF-8 字串元素相關資料的副本。透過 malloc() 取得緩衝區的記憶體，如果不再需要記憶體，呼叫端應使用 Free() 釋出該緩衝區。

詳細資料

參數

`[out] buf`	指標的參照，該指標會在成功時指派 `dataLen` 個位元組的堆積分配緩衝區。
`[out] dataLen`	`buf` 儲存成功時大小的儲存空間參照 (以位元組為單位)。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 位元組或 UTF8 字串，或是讀取器未位於元素上。
`WEAVE_ERROR_NO_MEMORY`	如果無法分配記憶體給輸出緩衝區。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE`	如果目標平台不支援 Malloc() 和 free()。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

DupString

WEAVE_ERROR DupString(
  char *& buf
)

分配並傳回含有目前位元組或 UTF8 字串之空值結束值的緩衝區。

這個方法會為建立緩衝區，並傳回目前位置的位元組或 UTF-8 字串元素，並以空值結尾的資料副本。透過 malloc() 取得緩衝區的記憶體，如果不再需要記憶體，呼叫端應使用 Free() 釋出該緩衝區。

詳細資料

參數

[out] buf

指標的參照，其堆積分配的緩衝區會在成功時指派。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 位元組或 UTF8 字串，或是讀取器未位於元素上。
`WEAVE_ERROR_NO_MEMORY`	如果無法分配記憶體給輸出緩衝區。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE`	如果目標平台不支援 Malloc() 和 free()。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

準備用來讀取 TLV 容器元素成員的 TLVReader 物件。

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

呼叫 EnterContainer() 時，TLVReader 物件必須放置在容器元素上才能讀取。這個方法會將 TLVType 值的參照做為引數，以便在讀取容器時儲存讀者背景資訊。

EnterContainer() 方法傳回時，讀取器的位置緊接在容器的第一個成員「之前」。重複呼叫 Next() 會將讀取器前進至集合的成員，直到抵達終點為止，屆時讀取器就會傳回 WEAVE_END_OF_TLV。

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

詳細資料

參數

[out] outerContainerType

這是 TLVType 的參照，用於接收讀者背景資訊。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果目前元素未置於容器元素上，

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

完成 TLV 容器讀取作業，並準備 TLVReader 物件在容器之後讀取元素。

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

ExitContainer() 傳回時，讀取器的位置緊跟著容器的第一個元素。此時，應用程式可以利用 Next() 方法，前往任何剩餘元素。

呼叫 EnterContainer() 後，應用程式可以隨時在讀取器上呼叫 ExitContainer()，不論基礎容器中的所有元素是否已讀取。

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

詳細資料

參數

[in] outerContainerType

EnterContainer() 方法傳回的 TLVType 值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果讀取器上尚未呼叫 OpenContainer()，或是容器讀取器與傳遞至 OpenContainer() 方法的容器不相符，則進行了。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果讀取器在無效環境中遇到 TLV 標記。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

取得

WEAVE_ERROR Get(
  bool & v
)

取得目前元素的值做為布林值類型。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 布林值類型，或是讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  int8_t & v
)

取得目前元素的值，為 8 位元帶正負號整數。

如果編碼的整數值大於輸出資料類型，則結果值將被截斷。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  int16_t & v
)

以 16 位元帶正負號整數取得目前元素的值。

如果編碼的整數值大於輸出資料類型，則結果值將被截斷。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  int32_t & v
)

以 32 位元帶正負號整數取得目前元素的值。

如果編碼的整數值大於輸出資料類型，則結果值將被截斷。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  int64_t & v
)

以 64 位元帶正負號整數取得目前元素的值。

如果編碼的整數值大於輸出資料類型，則結果值將被截斷。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  uint8_t & v
)

以 8 位元無正負號整數取得目前元素的值。

如果編碼的整數值大於輸出資料類型，則結果值將被截斷。同樣地，如果編碼的整數值為負數，則會將該值轉換成無正負號。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  uint16_t & v
)

以 16 位元無正負號整數取得目前元素的值。

如果編碼的整數值大於輸出資料類型，則結果值將被截斷。同樣地，如果編碼的整數值為負數，則會將該值轉換成無正負號。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  uint32_t & v
)

以 32 位元無正負號整數取得目前元素的值。

如果編碼的整數值大於輸出資料類型，則結果值將被截斷。同樣地，如果編碼的整數值為負數，則會將該值轉換成無正負號。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  uint64_t & v
)

以 64 位元無正負號整數取得目前元素的值。

如果編碼的整數值是負數，則會將該值轉換成無正負號。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 整數類型 (帶正負號或無正負號)，或讀取器未位於元素上。

取得

WEAVE_ERROR Get(
  float & v
)

取得

WEAVE_ERROR Get(
  double & v
)

取得目前元素的值，做為雙精度浮點數。

詳細資料

參數

[out] v

接收與目前 TLV 元素相關聯的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 浮點類型，或讀取器未位於元素上。

GetBufHandle

uintptr_t GetBufHandle(
  void
) const

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

取得目前位元組或 UTF8 字串元素的值。

如要判斷所需的輸入緩衝區大小，請先呼叫 GetLength() 方法，再呼叫 GetBytes()。

詳細資料

參數

`[in] buf`	指向用來接收字串資料的緩衝區指標。
`[in] bufSize`	`buf` 指向的緩衝區大小 (以位元組為單位)。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 位元組或 UTF8 字串，或是讀取器未位於元素上。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果提供的緩衝區太小，無法保存與目前元素相關聯的資料。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

GetContainerType

TLVType GetContainerType(
  void
) const

傳回 TLVReader 目前正在讀取的容器類型。

GetContainerType() 方法會傳回 TLVReader 讀取其中的 TLV 容器類型。如果 TLVReader 放置在 TLV 編碼的外層 (即最外側 TLV 元素的前後)，此方法就會傳回 kTLVType_NotSpecified。

詳細資料
傳回	目前容器的 TLVType；如果 TLVReader 不在容器內，則為 kTLVType_NotSpecified。

GetControlByte

uint16_t GetControlByte(
  void
) const

傳回與目前 TLV 元素相關聯的控制位元組。

在理想情況下，任何人都不需要知道控制位元組，而且只有 TLV 的內部實作才能夠存取控制位元組。不過，如果能存取控制位元組，TLV 偵錯公用程式 (在相當接近 TLV 緩衝區內容時，會嘗試解碼標記控制位元組) 來進行偵錯。

詳細資料
傳回	一個無正負號整數，內含與目前 TLV 元素相關聯的控制位元組。如果讀取器未位於元素「on」，就會傳回 kTLVControlByte_NotSpecified。

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

取得 TLV 位元組或 UTF8 字串元素的初始編碼位元組指標。

這個方法會在基礎輸入緩衝區中，傳回已編碼字串值的直接指標。這個方法需要字串值全部存在於單一緩衝區中，才能成功。否則，此方法會傳回 WEAVE_ERROR_TLV_UNDERRUN。如此一來，從多個不連續緩衝區讀取資料時，這個方法就會受到限制。

詳細資料

參數

[out] data

指向基礎字串資料指標的 const 指標參照。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 位元組或 UTF8 字串，或是讀取器未位於元素上。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼太早結束，或目前字串元素的值不在單一連續緩衝區中。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

GetLength

uint32_t GetLength(
  void
) const

傳回與目前 TLV 元素相關聯的資料長度。

資料長度只適用於 UTF8 字串或位元組字串的元素。如果是 UTF8 字串，傳回的值是字串中的位元組數，而非字元數。

詳細資料
傳回	與目前 TLV 元素相關聯的資料長度 (以位元組為單位)；如果目前元素不是 UTF8 字串或位元組字串，或是讀取器不在元素上，則為 0。

GetLengthRead

uint32_t GetLengthRead(
  void
) const

傳回讀取器初始化後讀取的位元組總數。

詳細資料
傳回	讀取器初始化後讀取的位元組總數。

GetReadPoint

const uint8_t * GetReadPoint(
  void
) const

取得與讀取器目前位置相對應的基礎輸入緩衝區的點。

詳細資料
傳回	指向對應讀取器目前位置的基礎輸入緩衝區的指標。

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const

傳回在達到讀取長度上限前可讀取的位元組總數。

詳細資料
傳回	在達到讀取長度上限前可讀取的位元組總數。

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

取得目前位元組或 UTF8 字串元素的值，做為空值終止字串。

如要判斷所需的輸入緩衝區大小，請先呼叫 GetLength() 方法，再呼叫 GetBytes()。輸入緩衝區至少要有一個位元組，超過字串長度才能容納空值字元。

詳細資料

參數

`[in] buf`	指向用來接收位元組字串資料的緩衝區指標。
`[in] bufSize`	`buf` 指向的緩衝區大小 (以位元組為單位)。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果目前元素不是 TLV 位元組或 UTF8 字串，或是讀取器未位於元素上。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果提供的緩衝區太小，無法保存與目前元素相關聯的資料。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

GetTag

uint64_t GetTag(
  void
) const

傳回與目前 TLV 元素相關聯的標記。

GetTag() 傳回的值可與標記公用程式函式 (IsProfileTag()、IsContextTag()、ProfileIdFromTag() 等) 搭配使用，以判斷代碼類型及擷取各種標記欄位值。

詳細資料
傳回	一個無正負號整數，內含與目前 TLV 元素相關聯的標記相關資訊。

GetType

TLVType GetType(
  void
) const

傳回目前 TLV 元素的類型。

詳細資料
傳回	這個 TLVType 值會說明目前 TLV 元素的資料類型。如果讀取器未位於 TLV 元素上，傳回值會是 kTLVType_NotSpecified。

Init

void Init(
  const TLVReader & aReader
)

初始化另一個 TLVReader 物件的 TLVReader 物件。

詳細資料

參數

[in] aReader

對 TLVReader 進行初始化的唯讀參照。

Init

void Init(
  const uint8_t *data,
  uint32_t dataLen
)

初始化要讀取單一輸入緩衝區的 TLVReader 物件。

詳細資料

參數

`[in] data`	指向包含要剖析的 TLV 資料的緩衝區指標。
`[in] dataLen`	要剖析的 TLV 資料長度。

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

初始化要從單一 PacketBuffer 讀取的 TLVReader 物件。

剖析會從緩衝區的起始位置 (buf->DataStart()) 開始，並持續到緩衝區中的資料末端 (以 buf->Datalen() 表示)，或者是 maxLen 位元組已剖析完畢。

詳細資料

參數

`[in] buf`	這個 PacketBuffer 的指標包含要剖析的 TLV 資料。
`[in] maxLen`	要剖析的位元組數上限。為輸入緩衝區的預設資料量。

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen,
  bool allowDiscontiguousBuffers
)

初始化 TLVReader 物件來讀取一或多個 PacketBuffer。

剖析會從初始緩衝區的起始位置 (buf->DataStart()) 開始。如果 allowDiscontiguousBuffers 為 true，讀取器會通過透過 Next() 指標連結的緩衝區鏈結。剖析作業會持續進行，直到已使用緩衝區鏈結中的所有資料 (如 buf->Datalen() 表示) 或 maxLen 位元組已剖析為止。

詳細資料

參數

`[in] buf`	這個 PacketBuffer 的指標包含要剖析的 TLV 資料。
`[in] maxLen`	要剖析的位元組數上限。預設為輸入緩衝區鏈中的資料總量。
`[in] allowDiscontiguousBuffers`	如果為 true，在已使用目前緩衝區中的所有資料後，前往鏈結中的下一個緩衝區。如果為 false，請在初始緩衝區結束時停止剖析。

繼續

WEAVE_ERROR Next(
  void
)

將 TLVReader 物件導向下一個要讀取的 TLV 元素。

Next() 方法會將讀者物件放置在位於相同遏制環境的 TLV 編碼中，下一個元素。特別是如果讀取器的位置位於 TLV 編碼的最外層，則呼叫 Next() 會將讀取器導向下一個最頂層的元素。如果讀取器位於 TLV 容器元素 (結構、陣列或路徑) 中，則呼叫 Next() 會引導讀取器前往容器的下一個成員元素。

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

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

詳細資料

傳回值

`WEAVE_NO_ERROR`	讀卡機是否成功放置在新元素上。
`WEAVE_END_OF_TLV`	沒有其他可用元素時。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果讀取器在無效環境中遇到 TLV 標記。
`WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG`	如果讀取器遇到隱含編碼的 TLV 標記，但該標記的對應設定檔 ID 不明。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

繼續

WEAVE_ERROR Next(
  TLVType expectedType,
  uint64_t expectedTag
)

將 TLVReader 物件移至下一個要讀取的 TLV 元素，宣告新元素的類型和標記。

Next(TLVTypeexpectedType, uint64_texpectedTag) 方法的行為與 Next() 相同，但會驗證新 TLV 元素的類型和標記是否與提供的引數相符，

詳細資料

參數

`[in] expectedType`	下一個元素的預期資料類型。
`[in] expectedTag`	下一個元素的預期標記。

傳回值

`WEAVE_NO_ERROR`	讀卡機是否成功放置在新元素上。
`WEAVE_END_OF_TLV`	沒有其他可用元素時。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果新元素的類型與 `expectedType` 引數的值不符，
`WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT`	如果與新元素相關聯的標記不符合 `expectedTag` 引數的值，
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果讀取器在無效環境中遇到 TLV 標記。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

OpenContainer

WEAVE_ERROR OpenContainer(
  TLVReader & containerReader
)

初始化新的 TLVReader 物件來讀取 TLV 容器元素的成員。

OpenContainer() 方法會初始化新的 TLVReader 物件來讀取 TLV 容器 (結構、陣列或路徑) 的成員元素。呼叫 OpenContainer() 時，目前的 TLVReader 物件必須置於要讀取的容器元素上。此方法會將對新讀取器的參照當做唯一引數，初始化後即可讀取容器。這種讀取器稱為「容器讀取器」，而呼叫 OpenContainer() 的讀取器則稱為「父項讀取器」。

OpenContainer() 方法傳回時，容器讀取器會緊接在容器的第一個成員之前。在容器讀取器上呼叫 Next() 會穿越集合成員，直到到達結束為止，此時讀取器就會傳回 WEAVE_END_OF_TLV。

容器讀取器開啟時，應用程式不得呼叫父項讀取器，也不得以其他方式變更父項讀取器的狀態。應用程式使用容器讀取器完成之後，必須在父項讀取器上呼叫 CloseContainer()，並傳送容器讀取器做為引數，藉此關閉應用程式。應用程式可能隨時關閉容器讀取器，不論是否讀取基礎容器中的所有元素。容器讀取器關閉後，應用程式可能會繼續使用父項讀取器。

容器讀取器會繼承父項讀取器的各種設定屬性。包括：

隱含設定檔 ID (ImplicitProfileId)
應用程式資料點 (AppData)
GetNextBuffer 函式指標

詳細資料

參數

[out] containerReader

TLVReader 物件的參照，用於讀取目前容器元素的成員。與提供的物件相關聯的任何資料都會覆寫。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果目前元素未置於容器元素上，

略過

WEAVE_ERROR Skip(
  void
)

將 TLVReader 物件移至目前的 TLV 元素之後。

Skip() 方法會在目前的 TLV 元素之後立即放置閱讀器物件，因此後續呼叫 Next() 時，系統會將讀取器導向下列元素。和 Next() 一樣，如果讀取器在呼叫期間位於容器元素上，就會略過容器的成員。如果讀取器尚未位於任何元素上，位置則維持不變。

詳細資料

傳回值

`WEAVE_NO_ERROR`	讀卡機是否成功放置在新元素上。
`WEAVE_END_OF_TLV`	沒有其他可用元素時。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果讀取器在無效環境中遇到 TLV 標記。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)

驗證 TVLReader 物件是否位於 TLV 容器的結尾。

VerifyEndOfContainer() 方法驗證在目前的 TLV 容器中，沒有其他可以讀取的 TLV 元素。這個方法十分便利，相當於呼叫 Next() 並檢查 WEAVE_END_OF_TLV 的回傳值。

詳細資料

傳回值

`WEAVE_NO_ERROR`	如果沒有要讀取的 TLV 元素。
`WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT`	集合中發現其他 TLV 元素。
`WEAVE_ERROR_TLV_UNDERRUN`	如果基礎 TLV 編碼已過早結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果讀取器在無效環境中遇到 TLV 標記。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

受保護的函式

ClearElementState

void ClearElementState(
  void
)

清除 TLVReader 狀態。

這個方法可用來在第一個 TLV 之前、介於 TLV 之間或最後一個 TLV 之間放置讀卡機。

ElementType

TLVElementType ElementType(
  void
) const

這是私人方法，會從 mControlByte 傳回 TLVElementType。

EnsureData

WEAVE_ERROR EnsureData(
  WEAVE_ERROR noDataErr
)

GetElementHeadLength

WEAVE_ERROR GetElementHeadLength(
  uint8_t & elemHeadBytes
) const

這是一種私人方法，用來計算 TLV 元素頭部的長度。

IsContainerOpen

bool IsContainerOpen(
  void
) const

ReadData

WEAVE_ERROR ReadData(
  uint8_t *buf,
  uint32_t len
)

ReadElement

WEAVE_ERROR ReadElement(
  void
)

ReadTag

uint64_t ReadTag(
  TLVTagControl tagControl,
  const uint8_t *& p
)

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

SkipData

WEAVE_ERROR SkipData(
  void
)

透過不使用目的地緩衝區的方式讀取，略過目前 TLV 中包含的任何資料。

詳細資料

傳回值

`WEAVE_NO_ERROR`	確認讀取器已順利放置在資料的結尾。
`other`	所設 GetNextBuffer() 函式傳回的其他 Weave 或平台錯誤代碼。只有在 GetNextBuffer 為非空值時，才能使用此函式。

SkipToEndOfContainer

WEAVE_ERROR SkipToEndOfContainer(
  void
)

VerifyElement

WEAVE_ERROR VerifyElement(
  void
)

受保護的靜態函式

FailGetNextBuffer

WEAVE_ERROR FailGetNextBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)

GetNextPacketBuffer

WEAVE_ERROR GetNextPacketBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)