本頁面由 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` 實作 TLVWriterFinalizeBuffer 函式，以便寫入至 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` 包含目前緩衝區中「unused」空間的位元組數量。結束時，`bufLen` 應該包含可寫入新輸出緩衝區的位元組數上限。

傳回值

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

公開屬性

AppData

void * AppData

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

FinalizeBuffer

FinalizeBufferFunct FinalizeBuffer

指向 TLVWriter 完成時呼叫的函式指標。

每當呼叫 Finalize() 方法時，TLVWriter 物件就會呼叫 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 元素。此時，您應將提供的容器寫入器視為「已初始化」，且未經重新初始化才能使用。

詳細說明

參數

[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() 函式傳回的 Weave 或平台特定錯誤，或由與讀取器物件相關聯的 GetNextBuffer() 函式傳回。

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() 函式傳回的 Weave 或平台特定錯誤，或由與讀取器物件相關聯的 GetNextBuffer() 函式傳回。

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() 函式傳回的 Weave 或平台特定錯誤，或由與讀取器物件相關聯的 GetNextBuffer() 函式傳回。

CopyElement

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

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

CopyElement() 方法可對類型、標記和值取自 TLVReader 物件的新 TLV 元素進行編碼。呼叫方法時，提供的讀取器物件應置於來源 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() 函式傳回的 Weave 或平台特定錯誤，或由與讀取器物件相關聯的 GetNextBuffer() 函式傳回。

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 元素。

注意：呼叫 EndContainer() 並不會撤銷對 StartContainer() 和 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，系統會視需要分配其他 PacketBuffers 並鏈結至提供的緩衝區，以容納寫入的資料量。如果指定的輸出緩衝區已經是緩衝區鏈結的中心，在分配任何新的緩衝區之前，系統會先將輸出內容寫入鏈結中的後續緩衝區。

詳細說明

參數

`[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 或平台特定錯誤。

最佳做法，

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 或平台特定錯誤。

最佳做法，

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 或平台特定錯誤。

最佳做法，

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

將 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 或平台特定錯誤。

最佳做法，

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 或平台特定錯誤。

最佳做法，

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

將 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`	指向一個緩衝區，其中包含 0 個將成為新容器成員的已編碼 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 功能可以使用時，函式可以將結果字串輸出至不連續的基礎儲存空間。實作支援下列 Printf 強化功能：

平台提供以回呼為基礎的 vcbprintf，可讓您呼叫自訂回呼來取代 Puchar。

平台提供名為 vsnprintf_ex 的 vsnprintf 變化版本，其行為與 vsnprintf 完全相同，差別在於平台有略過輸出內容的前 n 個字元。

請注意，雖然回呼式函式可能最簡單的方式，且使用的程式碼數量最少，但 vsprintf_ex 多元函式會使用較少的堆疊。

如果以上方法都無法使用，但平台提供 malloc，函式會分配暫時緩衝區來保留輸出內容。如果平台並未對 printf 系列或 malloc 進行強化，系統會截斷輸出內容，使其符合目前 TLV 儲存空間中的連續狀態

詳細說明

參數

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

傳回值

`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 或平台特定錯誤。

副總裁

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

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

平台提供以回呼為基礎的 vcbprintf，可讓您呼叫自訂回呼來取代 Puchar。

平台提供名為 vsnprintf_ex 的 vsnprintf 變化版本，其行為與 vsnprintf 完全相同，差別在於平台有略過輸出內容的前 n 個字元。

請注意，雖然回呼式函式可能最簡單的方式，且使用的程式碼數量最少，但 vsprintf_ex 多元函式會使用較少的堆疊。

詳細說明

參數

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

傳回值

`WEAVE_NO_ERROR`	如果方法成功。
`other`	如果對 TLVWriter 方法 `WriteElementHead` 或 `GetNewBuffer` 的基本呼叫失敗，這些錯誤會立即轉送至呼叫堆疊。

公開的靜態函式

FinalizePacketBuffer

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

實作 TLVWriterFinalizeBuffer 函式，以便寫入至 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() 函式視需要分配一或多個 PacketBuffers 鏈結，以便儲存編碼，為 TLVWriter 提供新的輸出空間。函式的設計是指派給 TLVWriter GetNewBuffer 函式指標。

請注意，將 GetNewPacketBuffer 與 TLVWriter 搭配使用時，也應使用對應的 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
)