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

nl::Weave::TLV::TLVWriter

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

提供高效率的編碼器，以 Weave TLV 格式寫入資料。

摘要

TLVWriter 可為 Weave TLV 資料實作正向串流樣式編碼器。應用程式會呼叫其中一個寫入者的 Put() 方法，並視需要傳送相關標記和值資訊，將資料寫入編碼。同樣地，應用程式可以呼叫寫入者的 OpenContainer() 或 EnterContainer() 方法，來編碼 TLV 容器類型 (結構、陣列或路徑)。

TLVWriter 物件可以直接將資料寫入固定的輸出緩衝區，或是一或多個 PacketBuffer 物件的鏈結。此外，應用程式可以提供自己的 GetNewBuffer 和 FinalizeBuffer 函式，將輸出內容導向至任意目的地，例如通訊端或事件佇列。

繼承

直接已知的子類別： nl::Weave::TLV::CircularTLVWriter

受保護的類型
`@72{ kEndOfContainerMarkerSize = 1 }`	列舉

公開類型
`FinalizeBufferFunct)(TLVWriter &writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t bufLen)`	WEAVE_ERROR() `WEAVE_ERROR(` 用於執行 TLVWriter 物件輸出的函式。
`GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen)`	WEAVE_ERROR() `WEAVE_ERROR(` 此函式可為 TLVWriter 提供新的輸出緩衝區空間。

公開屬性
`AppData`	`void *` 可用於應用程式特定資料的指標欄位。
`FinalizeBuffer`	`FinalizeBufferFunct` 一個在完成 TLVWriter 時呼叫的函式指標。
`GetNewBuffer`	`GetNewBufferFunct` 指向向 TLVWriter 提供新輸出緩衝區空間的函式指標。
`ImplicitProfileId`	`uint32_t` 應以隱含格式編碼的標記設定檔 ID。

受保護的屬性
`mBufHandle`	`uintptr_t`
`mBufStart`	`uint8_t *`
`mContainerType`	`TLVType`
`mLenWritten`	`uint32_t`
`mMaxLen`	`uint32_t`
`mRemainingLen`	`uint32_t`
`mWritePoint`	`uint8_t *`

公開函式
`CloseContainer(TLVWriter & containerWriter)`	`WEAVE_ERROR` 在呼叫 OpenContainer() 後，完成 TLV 容器寫入。
`ContinuePutBytes(const uint8_t *buf, uint32_t len)`	`WEAVE_ERROR` 對 TLV 位元組字串值進行編碼。
`CopyContainer(TLVReader & container)`	`WEAVE_ERROR` 從 TLVReader 物件複製 TLV 容器元素。
`CopyContainer(uint64_t tag, TLVReader & container)`	`WEAVE_ERROR` 從預先編碼的成員元素組合中，對 TLV 容器元素進行編碼。
`CopyContainer(uint64_t tag, const uint8_t *encodedContainer, uint16_t encodedContainerLen)`	`WEAVE_ERROR` 這個程式碼會編碼 TLV 容器元素，其中包含預先編碼容器的成員元素。
`CopyElement(TLVReader & reader)`	`WEAVE_ERROR` 將讀取器物件中的 TLV 元素複製到寫入者。
`CopyElement(uint64_t tag, TLVReader & reader)`	`WEAVE_ERROR`
`EndContainer(TLVType outerContainerType)`	`WEAVE_ERROR` 完成 TLV 容器元素的編碼。
`Finalize(void)`	`WEAVE_ERROR` 完成 TLV 編碼的編寫。
`GetContainerType(void) const`	`TLVType` 傳回 TLVWriter 目前正在寫入的容器類型。
`GetLengthWritten(void)`	`uint32_t` 傳回寫入者初始化後已寫入的位元組總數。
`Init(uint8_t *buf, uint32_t maxLen)`	`void` 初始化 TLVWriter 物件，以便寫入單一輸出緩衝區。
`Init(PacketBuffer *buf, uint32_t maxLen)`	`void` 初始化 TLVWriter 物件，以便寫入單一 PacketBuffer。
`Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)`	`void` 初始化 TLVWriter 物件，以便寫入一或多個 PacketBuffers。
`InitMalloced(uint8_t *& outBuf, uint32_t initialBufSize, uint32_t maxLen)`	`void` 初始化 TLVWriter 物件，以便寫入動態緩衝區。
`OpenContainer(uint64_t tag, TLVType containerType, TLVWriter & containerWriter)`	`WEAVE_ERROR` 初始化新的 TLVWriter 物件，以便寫入 TLV 容器元素的成員。
`Put(uint64_t tag, int8_t v)`	`WEAVE_ERROR` 將 TLV 帶正負號整數值進行編碼。
`Put(uint64_t tag, int8_t v, bool preserveSize)`	`WEAVE_ERROR` 將 TLV 帶正負號整數值進行編碼。
`Put(uint64_t tag, int16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint8_t v)`	`WEAVE_ERROR` 將 TLV 無正負號整數值進行編碼。
`Put(uint64_t tag, uint8_t v, bool preserveSize)`	`WEAVE_ERROR` 將 TLV 無正負號整數值進行編碼。
`Put(uint64_t tag, uint16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint64_t v)`	`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` 對 TLV 浮點值進行編碼。
`PutBoolean(uint64_t tag, bool v)`	`WEAVE_ERROR` 對 TLV 布林值進行編碼。
`PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)`	`WEAVE_ERROR` 對 TLV 位元組字串值進行編碼。
`PutNull(uint64_t tag)`	`WEAVE_ERROR` 對 TLV 空值進行編碼。
`PutPreEncodedContainer(uint64_t tag, TLVType containerType, const uint8_t *data, uint32_t dataLen)`	`WEAVE_ERROR` 從預先編碼的成員元素組合中，對 TLV 容器元素進行編碼。
`PutString(uint64_t tag, const char *buf)`	`WEAVE_ERROR` 對 TLV UTF8 字串值進行編碼。
`PutString(uint64_t tag, const char *buf, uint32_t len)`	`WEAVE_ERROR` 對 TLV UTF8 字串值進行編碼。
`PutStringF(uint64_t tag, const char *fmt, ...)`	`WEAVE_ERROR` 根據 TLV 元素中的格式，將字串輸出編碼。
`StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)`	`WEAVE_ERROR` 開始編碼新的 TLV 容器元素。
`StartPutBytes(uint64_t tag, uint32_t totalLen)`	`WEAVE_ERROR` 將 TLV 位元組字串編碼至多個區塊。
`VPutStringF(uint64_t tag, const char *fmt, va_list ap)`	`WEAVE_ERROR` 根據 TLV 元素中的格式，將字串輸出編碼。

公開的靜態函式
`FinalizePacketBuffer(TLVWriter & writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t dataLen)`	`WEAVE_ERROR` 實作 TLVWriter FinalizeBuffer 函式，以便寫入 PacketBuffers 鏈結。
`GetNewBuffer_Malloced(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)`	`WEAVE_ERROR` 實作 TLVWriter GetNewBuffer 函式，以便寫入動態緩衝區。
`GetNewPacketBuffer(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)`	`WEAVE_ERROR` 實作 TLVWriter GetNewBuffer 函式，以便寫入 PacketBuffers 鏈結。

受保護的函式
`IsCloseContainerReserved(void) const`	`bool` 決定容器是否應在啟動 / 開啟容器時為 CloseContainer 符號保留空間。
`IsContainerOpen(void) const`	`bool`
`SetCloseContainerReserved(bool aCloseContainerReserved)`	`void` 設定容器是否應在啟動 / 開啟容器時保留 CloseContainer 符號的空間。
`SetContainerOpen(bool aContainerOpen)`	`void`
`WriteData(const uint8_t *p, uint32_t len)`	`WEAVE_ERROR`
`WriteElementHead(TLVElementType elemType, uint64_t tag, uint64_t lenOrVal)`	`WEAVE_ERROR`
`WriteElementWithData(TLVType type, uint64_t tag, const uint8_t *data, uint32_t dataLen)`	`WEAVE_ERROR`

受保護的類型

72 次

@72

公開類型

FinalizeBufferFunct

WEAVE_ERROR(* FinalizeBufferFunct)(TLVWriter &writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t bufLen)

用於執行 TLVWriter 物件輸出的函式。

呼叫 TLVWriter 的 Finalize() 方法時，會呼叫此類型的函式。此函式應執行任何與使用寫入者物件的輸出內容相關的必要清理或結尾作業。例如記錄編碼的最終長度，或是關閉檔案描述元等等。

詳細資料

參數

`[in] writer`	正在定案的 TLVWriter 物件的參照。
`[in,out] bufHandle`	由之前呼叫 `GetNewBuffer` 函式設定的 uintptr_t 結構定義值。
`[in,out] bufStart`	指向目前 (和最終) 輸出緩衝區開頭的指標。
`[in,out] bufLen`	由 `bufStart` 指向的緩衝區中包含的位元組數。

傳回值

`WEAVE_NO_ERROR`	如果成功完成定案。
`other`	其他 Weave 或平台專屬錯誤代碼，用於表示最終作業發生錯誤。

GetNewBufferFunct

WEAVE_ERROR(* GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen)

此函式可為 TLVWriter 提供新的輸出緩衝區空間。

此類型的函式可用來為 TLVWriter 進行寫入準備新的緩衝區空間。呼叫該函式時，該函式應傳回要寫入新資料的記憶體位置指標，以及相關的長度上限。此函式可以提供寫入空間，方法為分配新的緩衝區來保存資料，或清除現有緩衝區中之前寫入的資料。

詳細資料

參數

`[in] writer`	對要求新緩衝區空間的 TLVWriter 物件的參照。
`[in,out] bufHandle`	這是對 uintptr_t 值的參照，可供函式在呼叫之間儲存結構定義資料。這個值會在第一次呼叫前初始化為 0。
`[in,out] bufStart`	資料點的參照。在函式的項目上，`bufStart` 會指向目前輸出緩衝區的起點。結束時，`bufStart` 應指向新輸出緩衝區的開頭。新指標值可以與先前的值相同 (例如函式將現有資料複製到其他位置)，也可以指向全新位置。
`[in,out] bufLen`	無正負號整數的參照。在函式的項目上，`bufLen` 包含目前緩衝區中未使用的空間位元組數。結束時，`bufLen` 會包含可寫入新輸出緩衝區的位元組數上限。

傳回值

`WEAVE_NO_ERROR`	如果該函式能為寫入者提供更多緩衝區空間。
`other`	其他 Weave 或平台專屬的錯誤代碼，表示發生錯誤，導致函式無法產生額外的緩衝區空間。

公開屬性

AppData

void * AppData

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

FinalizeBuffer

FinalizeBufferFunct FinalizeBuffer

一個在完成 TLVWriter 時呼叫的函式指標。

TLVWriter 物件會在呼叫 Finalize() 方法時呼叫 FinalizeBuffer 函式。應用程式可以在呼叫 Finalize() 之前的任何時間點設定函式指標。根據預設，指標設為 NULL，因此 Finalize() 方法會略過呼叫函式。

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

GetNewBuffer

GetNewBufferFunct GetNewBuffer

指向向 TLVWriter 提供新輸出緩衝區空間的函式指標。

每當嘗試寫入超過目前輸出緩衝區大小的資料時，TLVWriter 物件就會呼叫 GetNewBuffer 函式。如果設為 NULL (預設值)，如果輸出資料溢位目前的緩衝區，寫入者將傳回 WEAVE_ERROR_NO_MEMORY。

任何時候，應用程式都能設定 GetNewBuffer，但通常是在寫入寫入者初始化時設定。

如需有關實作 GetNewBuffer 函式的其他資訊，請參閱 GetNewBufferFunct 類型定義。

ImplicitProfileId

uint32_t ImplicitProfileId

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

當系統要求寫入者對新元素進行編碼時，如果與新元素相關聯的標記資料 ID 與 ImplicitProfileId 成員的值相符，撰寫者就會以隱含形式將標記編碼，並在過程中省略設定檔 ID。

根據預設，ImplicitProfileId 屬性會設為 kProfileIdNotSpecified，以指示寫入者不要發出隱含編碼的標記。應用程式可隨時設定 ImplicitProfileId，從編碼的目前點開始，以隱含形式啟用編碼標記。適當的設定檔 ID 通常取決於當下說出的應用程式內容或通訊協定。

注意：ImplicitProfileId 成員的值只會影響設定檔專屬標記的編碼。內容專屬標記的編碼會維持不變。

受保護的屬性

mBufHandle

uintptr_t mBufHandle

mBufStart

uint8_t * mBufStart

mContainerType

TLVType mContainerType

mLenWritten

uint32_t mLenWritten

mMaxLen

uint32_t mMaxLen

mRemainingLen

uint32_t mRemainingLen

mWritePoint

uint8_t * mWritePoint

公開函式

CloseContainer

WEAVE_ERROR CloseContainer(
  TLVWriter & containerWriter
)

在呼叫 OpenContainer() 後，完成 TLV 容器寫入。

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

CloseContainer() 傳回後，應用程式可繼續使用父項寫入器，編寫在容器元素後方顯示的其他 TLV 元素。此時，提供的容器寫入器應視為「de-initialized」且必須先重新初始化才能使用。

詳細資料

參數

[in] containerWriter

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

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果提供的容器寫入器狀態不正確。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果其他容器寫入器已在提供的容器寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果完成容器編碼，就會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

ContinuePutBytes

WEAVE_ERROR ContinuePutBytes(
  const uint8_t *buf,
  uint32_t len
)

對 TLV 位元組字串值進行編碼。

此值應與 StartPutBytes 搭配使用。

詳細資料

參數

`[in] buf`	指向要編碼位元組字串的緩衝區指標。
`[in] len`	要編碼的位元組數。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

CopyContainer

WEAVE_ERROR CopyContainer(
  TLVReader & container
)

從 TLVReader 物件複製 TLV 容器元素。

CopyContainer() 會複製位於 TLVReader 物件目前位置的預先編碼容器元素，藉此編碼新的 TLV 容器元素。這個方法會在一次呼叫中寫入完整的新容器元素，並從來源編碼複製容器的類型、標記和元素。當方法傳回時，寫入者物件可用於在容器元素後方寫入其他 TLV 元素。

詳細資料

參數

[in] container

TLVReader 物件的參照，用於識別要複製的預先編碼 TLV 容器。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果提供的讀取器不在容器元素上。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_TLV_UNDERRUN`	與所提供讀取器相關聯的基礎 TLV 編碼已提前結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果提供的讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果提供的讀取器在無效的情況下遇到 TLV 標記，或是與來源容器相關聯的標記在寫入新容器時無效或不當。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	已設定的 GetNewBuffer() 或 FinalizeBuffer() 函式，或與讀取器物件相關聯的 GetNextBuffer() 函式傳回的其他 Weave 或平台特定錯誤。

CopyContainer

WEAVE_ERROR CopyContainer(
  uint64_t tag,
  TLVReader & container
)

從預先編碼的成員元素組合中，對 TLV 容器元素進行編碼。

CopyContainer() 方法會編碼新的 TLV 容器元素 (結構、陣列或路徑)，其中包含從 TLVReader 物件擷取的一組成員元素。呼叫此方法時，提供的讀取器物件應放置在 TLV 容器元素上。新編碼的容器將具有與輸入容器相同的類型和成員。系統會將新容器的標記指定為輸入參數。

當方法傳回時，寫入者物件可用於在容器元素後方寫入其他 TLV 元素。

詳細資料

參數

`[in] tag`	要與容器編碼的 TLV 標記；如果容器應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] container`	TLVReader 物件的參照，用於識別預先編碼的 TLV 容器，其類型和成員應複製。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果提供的讀取器不在容器元素上。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_TLV_UNDERRUN`	與所提供讀取器相關聯的基礎 TLV 編碼已提前結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果提供的讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果提供的讀取器在無效的情況下遇到 TLV 標記，或是提供的標記在寫入新容器時無效或不當。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	已設定的 GetNewBuffer() 或 FinalizeBuffer() 函式，或與讀取器物件相關聯的 GetNextBuffer() 函式傳回的其他 Weave 或平台特定錯誤。

CopyContainer

WEAVE_ERROR CopyContainer(
  uint64_t tag,
  const uint8_t *encodedContainer,
  uint16_t encodedContainerLen
)

這個程式碼會編碼 TLV 容器元素，其中包含預先編碼容器的成員元素。

CopyContainer() 方法會編碼新的 TLV 容器元素 (結構、陣列或路徑)，其中包含一組從預先編碼的容器內容中擷取的成員元素。呼叫此方法時，系統會將所提供輸入緩衝區中的資料剖析為 TLV 容器元素。系統會編寫與輸入容器具有相同類型和成員的新容器。系統會將新容器的標記指定為輸入參數。

當方法傳回時，寫入者物件可用於在容器元素後方寫入其他 TLV 元素。

詳細資料

參數

`[in] tag`	要與容器編碼的 TLV 標記；如果容器應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] encodedContainer`	包含預先編碼 TLV 容器的緩衝區，其類型和成員應複製。
`[in] encodedContainerLen`	預先編碼容器的長度 (以位元組為單位)。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_TLV_UNDERRUN`	如果編碼的容器已提前結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果編碼的容器包含無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果編碼的容器包含無效結構定義的 TLV 標記，或是提供的代碼在寫入新容器時無效或不當。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	已設定的 GetNewBuffer() 或 FinalizeBuffer() 函式，或與讀取器物件相關聯的 GetNextBuffer() 函式傳回的其他 Weave 或平台特定錯誤。

CopyElement

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

將讀取器物件中的 TLV 元素複製到寫入者。

CopyElement() 方法會對新的 TLV 元素進行編碼，其類型、標記和值皆取自 TLVReader 物件。呼叫此方法時，提供的讀取器物件應位於來源 TLV 元素上。新編碼的元素將具有與輸入容器相同的類型、標記和內容。如果提供的元素是 TLV 容器 (結構、陣列或路徑)，系統就會複製容器的完整內容。

詳細資料

參數

[in] reader

TLVReader 物件的參照，用於指定應複製的預先編碼 TLV 元素。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果提供的讀取器不在元素上，
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_TLV_UNDERRUN`	與所提供讀取器相關聯的基礎 TLV 編碼已提前結束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果提供的讀取器遇到無效或不支援的 TLV 元素類型。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果提供的讀取器在無效的情況下遇到 TLV 標記，或是提供的標記在寫入新容器時無效或不當。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	已設定的 GetNewBuffer() 或 FinalizeBuffer() 函式，或與讀取器物件相關聯的 GetNextBuffer() 函式傳回的其他 Weave 或平台特定錯誤。

CopyElement

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

EndContainer

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

完成 TLV 容器元素的編碼。

EndContainer() 方法會完成 TLV 容器元素的編碼，並在先前的 StartContainer() 呼叫之後還原 TLVWrite 物件的狀態。每次呼叫 StartContainer() 應用程式時，都必須對 EndContainer() 發出對應的呼叫，並傳遞 StartContainer() 呼叫傳回的 TLVType 值。EndContainer() 傳回後，寫入器物件可用於寫入符合容器元素的其他 TLV 元素。

注意：在呼叫 StartContainer() 和 EndContainer() 之間，寫入者設定所做的任何變更，並「不會」透過呼叫 EndContainer() 予以復原。舉例來說，容器結束時並未撤銷隱含設定檔 ID (ImplicitProfileId) 的變更。因此，應用程式有責任適時調整設定。

詳細資料

參數

[in] outerContainerType

StartContainer() 方法傳回的 TLVType 值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果沒有發出對應的 StartContainer() 呼叫。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

完成

WEAVE_ERROR Finalize(
  void
)

完成 TLV 編碼的編寫。

Finalize() 方法會完成將 TLV 編碼寫入基礎輸出緩衝區的程序。應用程式必須先呼叫此方法，才能使用緩衝區內容。只有在目前寫入者沒有開放容器寫入者的情況下，才能呼叫 Finalize()。(請參閱 OpenContainer())。

詳細資料

傳回值

`WEAVE_NO_ERROR`	如果編碼是否順利完成。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`other`	所設 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

GetContainerType

TLVType GetContainerType(
  void
) const

傳回 TLVWriter 目前正在寫入的容器類型。

GetContainerType() 方法會傳回 TLVWriter 目前寫入的 TLV 容器類型。如果 TLVWriter 並未在容器內寫入元素 (也就是在編碼最外層寫入)，此方法會傳回 kTLVType_NotSpecified。

詳細資料
傳回	目前容器的 TLVType；如果 TLVWriter 並未在容器內寫入元素，則為 kTLVType_NotSpecified。

GetLengthWritten

uint32_t GetLengthWritten(
  void
)

傳回寫入者初始化後已寫入的位元組總數。

詳細資料
傳回	寫入者初始化後寫入的位元組總數。

Init

void Init(
  uint8_t *buf,
  uint32_t maxLen
)

初始化 TLVWriter 物件，以便寫入單一輸出緩衝區。

詳細資料

參數

`[in] buf`	應寫入 TLV 的緩衝區指標。
`[in] maxLen`	可寫入輸出緩衝區的位元組數上限。

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

初始化 TLVWriter 物件，以便寫入單一 PacketBuffer。

在提供的緩衝區中，現有資料的最後一個位元組會立即開始寫入。

詳細資料

參數

`[in] buf`	應寫入 TLV 的 PacketBuffer 指標。
`[in] maxLen`	可寫入輸出緩衝區的位元組數上限。

Init

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

初始化 TLVWriter 物件，以便寫入一或多個 PacketBuffers。

寫入作業會立即開始在指定緩衝區中現有資料的最後一個位元組之後。如果 allowDiscontiguousBuffers 為 true，系統會視需要分配額外的 PacketBuffer，並鏈結至提供的緩衝區，以容納寫入的資料量。如果指定的輸出緩衝區已經是緩衝區鏈結的頭，則在分配任何新緩衝區之前，系統會將輸出內容寫入鏈結中的後續緩衝區。

詳細資料

參數

`[in] buf`	應寫入 TLV 資料的 PacketBuffer 指標。
`[in] maxLen`	可寫入輸出緩衝區的位元組數上限。
`[in] allowDiscontiguousBuffers`	如果為 true，請將資料寫入 PacketBuffers 鏈結，並視需要分配新的緩衝區，以便儲存寫入的資料。設為 false 時，如果寫入的資料超過初始輸出緩衝區的可用空間，則寫入作業會失敗，並顯示 WEAVE_ERROR_BUFFER_TOO_SMALL。

InitMalloced

void InitMalloced(
  uint8_t *& outBuf,
  uint32_t initialBufSize,
  uint32_t maxLen
)

初始化 TLVWriter 物件，以便寫入動態緩衝區。

詳細資料

參數

`[in] buf`	會接收已分配緩衝區的指標參照。
`[in] maxLen`	可寫入輸出緩衝區的位元組數上限。
`[in] initialBufSize`	應分配給緩衝區的初始位元組數。

OpenContainer

WEAVE_ERROR OpenContainer(
  uint64_t tag,
  TLVType containerType,
  TLVWriter & containerWriter
)

初始化新的 TLVWriter 物件，以便寫入 TLV 容器元素的成員。

OpenContainer() 方法用於將 TLV 容器元素 (結構、陣列或路徑) 寫入編碼。此方法會採用新容器的類型和標記 (如有)，以及針對寫入容器元素而初始化的新寫入者物件 (容器寫入者) 的參照。應用程式會使用容器寫入器寫入新容器的成員，然後呼叫 CloseContainer() 來完成容器編碼。

當容器寫入器開啟時，應用程式不得呼叫父項寫入者的狀態，也不得以其他方式變更父項寫入器的狀態。

容器寫入者會繼承父項寫入者的各種設定屬性。包括：

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

詳細資料

參數

`[in] tag`	要與容器編碼的 TLV 標記；如果容器應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] containerType`	要編碼的容器類型。必須是 `kTLVType_Structure`、`kTLVType_Array` 或 `kTLVType_Path` 其中之一。
`[out] containerWriter`	TLVWriter 物件的參照，用於寫入新容器元素的成員。與提供的物件相關聯的任何資料都會覆寫。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果 containerType 指定的值不正確，
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

將 TLV 帶正負號整數值進行編碼。

這是為了方便起見，此為成員函式超載。與上述函式的差別僅在於其接受的引數。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] v`	要編碼的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

Put

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

將 TLV 帶正負號整數值進行編碼。

這是為了方便起見，此為成員函式超載。與上述函式的差別僅在於其接受的引數。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] v`	要編碼的值。
`[in] preserveSize`	如果值應採用與輸入類型相同的位元組數編碼，則為「true」。如果值應以代表值所需的最少位元組數進行編碼，則為 False。注意：強烈建議應用程式將此參數設為 false。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

Put

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

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

Put

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

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

Put

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

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

將 TLV 無正負號整數值進行編碼。

這是為了方便起見，此為成員函式超載。與上述函式的差別僅在於其接受的引數。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] v`	要編碼的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

Put

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

將 TLV 無正負號整數值進行編碼。

這是為了方便起見，此為成員函式超載。與上述函式的差別僅在於其接受的引數。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] v`	要編碼的值。
`[in] preserveSize`	如果值應採用與輸入類型相同的位元組數編碼，則為「true」。如果值應以代表值所需的最少位元組數進行編碼，則為 False。注意：強烈建議應用程式將此參數設為 false。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

Put

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

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

Put

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

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

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
)

對 TLV 浮點值進行編碼。

這是為了方便起見，此為成員函式超載。與上述函式的差別僅在於其接受的引數。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] v`	要編碼的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

PutBoolean

WEAVE_ERROR PutBoolean(
  uint64_t tag,
  bool v
)

對 TLV 布林值進行編碼。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] v`	要編碼的值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

PutBytes

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

對 TLV 位元組字串值進行編碼。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] buf`	指向要編碼位元組字串的緩衝區指標。
`[in] len`	要編碼的位元組數。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

PutNull

WEAVE_ERROR PutNull(
  uint64_t tag
)

對 TLV 空值進行編碼。

詳細資料

參數

[in] tag

要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 AnonymousTag。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

PutPreEncodedContainer

WEAVE_ERROR PutPreEncodedContainer(
  uint64_t tag,
  TLVType containerType,
  const uint8_t *data,
  uint32_t dataLen
)

從預先編碼的成員元素組合中，對 TLV 容器元素進行編碼。

PutPreEncodedContainer() 方法會編碼新的 TLV 容器元素 (結構、陣列或路徑)，其中包含一組從預先編碼緩衝區擷取的成員元素。輸入緩衝區應該包含零或多個完整編碼的 TLV 元素，其中包含符合指定容器類型相關規則的標記 (例如結構成員必須含有標記，而陣列成員則不得)。

這個方法會在單一呼叫中將整個容器元素編碼。PutPreEncodedContainer() 傳回後，您可以使用作者物件在容器元素後方編寫其他 TLV 元素。

詳細資料

參數

`[in] tag`	要與容器編碼的 TLV 標記；如果容器應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] containerType`	要編碼的容器類型。必須是 `kTLVType_Structure`、`kTLVType_Array` 或 `kTLVType_Path` 其中之一。
`[in] data`	這個緩衝區指向一個包含零個已編碼 TLV 元素的緩衝區，該元素將成為新容器的成員。
`[in] dataLen`	`data` 緩衝區中的位元組數。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果 containerType 指定的值不正確，
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf
)

對 TLV UTF8 字串值進行編碼。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] buf`	要編碼的空值結尾 UTF-8 字串的指標。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

PutString

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

對 TLV UTF8 字串值進行編碼。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] buf`	要編碼的 UTF-8 字串指標。
`[in] len`	要編碼的字串長度 (以位元組為單位)。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

PutStringF

WEAVE_ERROR PutStringF(
  uint64_t tag,
  const char *fmt,
  ...
)

根據 TLV 元素中的格式，將字串輸出編碼。

PutStringF 是 sprintf 的類比，輸出結果儲存在 TLV 元素中，而非字元緩衝區。可以使用擴充 printf 功能時，該函式可以將結果字串輸出到不連續的基礎儲存空間。此實作支援下列列印強化功能：

平台提供回呼式 vcbprintf，可讓您呼叫自訂回呼取代 putchar。

平台提供名為 vsnprintf_ex 的 vsnprintf 變化版本，運作方式與 vsnprintf 完全相同，但有規定省略輸出內容的前 n 字元。

請注意，雖然回呼型函式最簡單且使用的程式碼數量最少，但 vsprintf_ex 各種函式所耗用的堆疊較少。

如果上述方法都無法使用，但平台提供 malloc，函式會分配暫存緩衝區來保存輸出內容。如果平台為 printf 系列或 Malloc 尚未提供強化項目，則輸出內容會遭到截斷，以符合目前 TLV 儲存空間的連續狀態

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] fmt`	用來設定引數清單格式的格式字串。遵循的語法和規則與 `printf` 函式系列的格式字串相同。
`[in] ...`	要根據這項設定在輸出值中設定格式的引數清單。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`other`	如果對 TLVWriter 方法 `WriteElementHead` 或 `GetNewBuffer` 的基礎呼叫失敗，其錯誤會立即轉至呼叫堆疊。

StartContainer

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

開始編碼新的 TLV 容器元素。

StartContainer() 方法的用途是將 TLV 容器元素 (結構、陣列或路徑) 寫入編碼。這個方法會採用新容器的類型和標記 (如有)，以及 TLVType 值的參照，在其用於寫入容器時，用來儲存寫入者目前的內容。

StartContainer() 方法傳回後，應用程式應使用目前的 TLVWriter 物件來寫入容器的元素。完成後，應用程式必須呼叫 EndContainer() 方法才能完成容器編碼。

詳細資料

參數

`[in] tag`	要與容器編碼的 TLV 標記；如果容器應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] containerType`	要編碼的容器類型。必須是 `kTLVType_Structure`、`kTLVType_Array` 或 `kTLVType_Path` 其中之一。
`[out] outerContainerType`	要接收寫入者背景的 TLVType 值。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	如果 containerType 指定的值不正確，
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

StartPutBytes

WEAVE_ERROR StartPutBytes(
  uint64_t tag,
  uint32_t totalLen
)

將 TLV 位元組字串編碼至多個區塊。

此值應與 ContinuePutBytes 搭配使用。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] totalLen`	要編碼的位元組總數。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	如果容器寫入器已在目前的寫入器上開啟，但尚未關閉。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果指定的標記值無效，或在寫入值的環境中不適當，就會發生這種情況。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果寫入這個值，會超過寫入寫入者時指定的位元組數上限。
`WEAVE_ERROR_NO_MEMORY`	如果嘗試分配輸出緩衝區因記憶體不足而失敗。
`other`	所設 GetNewBuffer() 或 FinalizeBuffer() 函式傳回的其他 Weave 或平台專用錯誤。

VPutStringF

WEAVE_ERROR VPutStringF(
  uint64_t tag,
  const char *fmt,
  va_list ap
)

根據 TLV 元素中的格式，將字串輸出編碼。

平台提供回呼式 vcbprintf，可讓您呼叫自訂回呼取代 putchar。

平台提供名為 vsnprintf_ex 的 vsnprintf 變化版本，運作方式與 vsnprintf 完全相同，但有規定省略輸出內容的前 n 字元。

請注意，雖然回呼型函式最簡單且使用的程式碼數量最少，但 vsprintf_ex 各種函式所耗用的堆疊較少。

詳細資料

參數

`[in] tag`	要與值編碼的 TLV 標記；如果值應在沒有標記的情況下編碼，則為 `AnonymousTag`。請使用以下其中一種標記定義函式 (ProfileTag()、ContextTag() 或 CommonTag()) 建構標記值。
`[in] fmt`	用來設定引數清單格式的格式字串。遵循的語法和規則與 `printf` 函式系列的格式字串相同。
`[in] ap`	要根據這項設定在輸出值中設定格式的引數清單。

傳回值

`WEAVE_NO_ERROR`	方法是否成功。
`other`	如果對 TLVWriter 方法 `WriteElementHead` 或 `GetNewBuffer` 的基礎呼叫失敗，其錯誤會立即轉至呼叫堆疊。

公開的靜態函式

FinalizePacketBuffer

WEAVE_ERROR FinalizePacketBuffer(
  TLVWriter & writer,
  uintptr_t bufHandle,
  uint8_t *bufStart,
  uint32_t dataLen
)

實作 TLVWriter FinalizeBuffer 函式，以便寫入 PacketBuffers 鏈結。

使用 TLVWriter 寫入 PacketBuffers 鏈結時，FinalizePacketBuffer() 函式會執行必要的最終作業。此函式旨在與 GetNewPacketBuffer() 函式搭配使用。

如要進一步瞭解 FinalizePacketBuffer() 函式的 API，請參閱 FinalizeBufferFunct 類型定義。

GetNewBuffer_Malloced

WEAVE_ERROR GetNewBuffer_Malloced(
  TLVWriter & writer,
  uintptr_t & bufHandle,
  uint8_t *& bufStart,
  uint32_t & bufLen
)

實作 TLVWriter GetNewBuffer 函式，以便寫入動態緩衝區。

GetNewBuffer_Malloced() 函式可以視需要將基礎動態緩衝區的大小加倍，以便儲存編碼，為 TLVWriter 提供新的輸出空間。此函式經過設計，會指派給 TLVWriter GetNewBuffer 函式指標。

如要進一步瞭解 GetNewBuffer_Malloced() 函式的 API，請參閱 GetNewBufferFunct 類型定義。

GetNewPacketBuffer

WEAVE_ERROR GetNewPacketBuffer(
  TLVWriter & writer,
  uintptr_t & bufHandle,
  uint8_t *& bufStart,
  uint32_t & bufLen
)

實作 TLVWriter GetNewBuffer 函式，以便寫入 PacketBuffers 鏈結。

GetNewPacketBuffer() 函式可以視需要分配一或多個 PacketBuffer 的鏈結來儲存編碼，藉此為 TLVWriter 提供新的輸出空間。此函式經過設計，會指派給 TLVWriter GetNewBuffer 函式指標。

請注意，搭配 TLVWriter 使用 GetNewPacketBuffer 時，應一併使用對應的 FinalizePacketBuffer() 函式 (或同等項目) 完成緩衝區鏈。

如要進一步瞭解 GetNewPacketBuffer() 函式的 API，請參閱 GetNewBufferFunct 類型定義。

受保護的函式

IsCloseContainerReserved

bool IsCloseContainerReserved(
  void
) const

決定容器是否應在啟動 / 開啟容器時為 CloseContainer 符號保留空間。

IsContainerOpen

bool IsContainerOpen(
  void
) const

SetCloseContainerReserved

void SetCloseContainerReserved(
  bool aCloseContainerReserved
)

設定容器是否應在啟動 / 開啟容器時保留 CloseContainer 符號的空間。

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

WriteData

WEAVE_ERROR WriteData(
  const uint8_t *p,
  uint32_t len
)

WriteElementHead

WEAVE_ERROR WriteElementHead(
  TLVElementType elemType,
  uint64_t tag,
  uint64_t lenOrVal
)

WriteElementWithData

WEAVE_ERROR WriteElementWithData(
  TLVType type,
  uint64_t tag,
  const uint8_t *data,
  uint32_t dataLen
)