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

nl::Weave::TLV::TLVReader

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

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

摘要

TLVReader 可以為 Weave TLV 資料實作僅限前瞻的「提取式」剖析器。TLVReader 物件會以遊標的形式運作，可用來疊代 TLV 元素並解讀內容。放置在元素上時，應用程式可以呼叫讀取器的 Get() 方法，查詢目前元素的類型和標記，並擷取任何相關聯的值。讀取器的 Next() 方法用於從元素前進到元素。

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

讀取器達到 TLV 編碼的結尾，或容器中的最後一個元素時，便會從 Next() 方法傳回 WEAVE_END_OF_TLV 錯誤，向應用程式發出信號。讀取器將繼續傳回 WEAVE_END_OF_TLV，直到重新啟動或目前的容器結束（透過 CloseContainer() / ExitContainer() ）。

TLVReader 物件可直接從固定的輸入緩衝區或一或多個 PacketBuffers 鏈結中剖析資料。此外，應用程式也可以提供 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` 準備 TLVReader 物件來讀取 TLV 容器元素的成員。
`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` 初始化 TLVReader 物件從單一 PacketBuffer 讀取。
`Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)`	`void` 初始化 TLVReader 物件，以便從一或多個 PacketBuffers 讀取。
`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() 後，應用程式應將容器讀取器視為「已初始化」，且除非重新初始化，否則無法再使用。

詳細說明

參數

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

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

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

呼叫 EnterContainer() 時，必須將 TLVReader 物件置於要讀取的容器元素上。此方法會將 TLVType 值的參照做為引數，用於在讀取容器時儲存讀取器的內容。

EnterContainer() 方法傳回時，讀取器會位於容器第一個成員「之前」。重複呼叫 Next() 會帶領讀取器導覽到集合的成員，直到 ID 結束為止，此時讀取器會傳回 WEAVE_END_OF_TLV。

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

詳細說明

參數

[out] outerContainerType

接收讀取器結構定義的 TLVType 值參照。

傳回值

`WEAVE_NO_ERROR`	如果方法成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果目前的元素並未放在容器元素上。

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

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

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

ExitContainer() 傳回時，讀取器會緊接在容器後面的第一個元素之前。從這時開始，應用程式即可使用 Next() 方法前往任何其他元素。

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

注意：呼叫 ExitContainer() 不會復原對 EnterContainer() 和 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 字串元素的值。

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

詳細說明

參數

`[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 Debug 公用程式 (在美化 TLV 緩衝區內容時，嘗試對標記控制項位元組進行解碼)。

詳細說明
傳回	一個未簽署的整數，內含與目前 TLV 元素相關聯的控制位元組。如果讀取器並未在元素上，則傳回 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 元素的類型。

詳細說明
傳回	說明目前 TLV 元素資料類型的 TLVType 值。如果讀取器沒有位於 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
)

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

剖析從緩衝區的起始位置 (buf->DataStart()) 開始，並持續到緩衝區中的資料結尾 (如 buf->Datalen() 註明)，或 maxLen 位元組被剖析。

詳細說明

參數

`[in] buf`	指向要剖析的 TLV 資料的 PacketBuffer 指標。
`[in] maxLen`	要剖析的位元組上限。預設值為輸入緩衝區中的資料量。

Init

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

初始化 TLVReader 物件，以便從一或多個 PacketBuffers 讀取。

剖析從初始緩衝區的起始位置 (buf->DataStart()) 開始。如果 allowDiscontinueiguousBuffers 為 true，讀取器會進展到由其 Next() 指標連結的緩衝區鏈。剖析功能會持續執行，直到緩衝區鏈結中的所有資料都經過取用 (如 buf->Datalen() 表示)，或 maxLen 位元組處於剖析狀態為止。

詳細說明

參數

`[in] buf`	指向要剖析的 TLV 資料的 PacketBuffer 指標。
`[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_t predictTag) 方法是一種便利的方法，其行為與 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
)