nl::編織：: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(*)
用來執行 TLVWriter 物件輸出結果的函式。
GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen) WEAVE_ERROR(*)
為 TLVWriter 提供新輸出緩衝區空間的函式。

公開屬性
AppData
void *
可用於應用程式特定資料的指標欄位。
FinalizeBuffer
指向 TLVWriter 完成時會呼叫的函式指標。
GetNewBuffer
指向 TLVWriter 的新輸出緩衝空間的函式指標。
ImplicitProfileId
uint32_t
應以隱含格式編碼的代碼設定檔編號。

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

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

公開的靜態函式
FinalizePacketBuffer(TLVWriter & writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t dataLen)
導入 TLVWriter FinalizeBuffer 函式，可寫入 PacketBuffers 鏈結。
GetNewBuffer_Malloced(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)
導入可寫入動態緩衝區的 TLVWriter GetNewBuffer 函式。
GetNewPacketBuffer(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)
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)
WriteElementHead(TLVElementType elemType, uint64_t tag, uint64_t lenOrVal)
WriteElementWithData(TLVType type, uint64_t tag, const uint8_t *data, uint32_t dataLen)

受保護類型

@72

 @72

公開類型

FinalizeBufferFunct

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

用來執行 TLVWriter 物件輸出結果的函式。

呼叫 TLVWriter's Finalize() 方法時，系統會呼叫這類函式。此函式預期應執行與使用寫入者物件的輸出相關的任何清除或敲定作業。例如記錄編碼的最後一個長度或關閉檔案描述元。

詳細資料
參數
[in] writer
參照的 TLVWriter 物件參考編號。
[in,out] bufHandle
先前呼叫 GetNewBuffer 函式所設定的 uintptr_t 內容值。
[in,out] bufStart
目前 (和最終) 輸出緩衝區開頭的指標。
[in,out] bufLen
緩衝區所含的位元組數，指向 bufStart。
傳回值
WEAVE_NO_ERROR
如果敲定成功。
other
其他總結或特定平台的錯誤代碼，表示在敲定期間發生錯誤。

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 或平台專屬的錯誤代碼，代表發生錯誤導致函式產生額外的緩衝空間。

公開屬性

應用程式資料

void * AppData

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

FinalizeBuffer

FinalizeBufferFunct FinalizeBuffer

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

TLVWriter 物件會在每次呼叫 Finalize() 方法時呼叫 FinalizeBuffer 函式。應用程式可在呼叫 Finalize() 之前的任何時間點設定函式指標。根據預設，指標會設為 NULL，如此就會讓 Finalize() 方法再次呼叫該函式。

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

取得新緩衝區

GetNewBufferFunct GetNewBuffer

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

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

GetNewBuffer 可隨時由應用程式設定，但通常在寫入器初始化時設定。

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

曝光設定檔 ID

uint32_t ImplicitProfileId

應以隱含格式編碼的代碼設定檔編號。

如果寫入者要對新元素進行編碼，如果與新元素相關聯的標記設定檔 ID 與 ImplicitProfileId 成員的值相符，寫入者就會以隱形式提供標記，並省略這個程序中的設定檔 ID。

ImplicitProfileId 屬性預設為 kProfileIdNotSpecified，指示寫入者不要傳送隱含編碼的標記。應用程式可隨時設定 ImplicitProfileId，以隱含形式啟用編碼標記，從編碼的當前時間點開始。要設定適當的設定檔 ID，通常取決於正在呼叫的應用程式或通訊協定的內容。

受保護的屬性

mBufHandling

uintptr_t mBufHandle

mBuf 開始

uint8_t * mBufStart

mContainer 類型

TLVType mContainerType

長版文字

uint32_t mLenWritten

最大 L

uint32_t mMaxLen

里姆 (LRemainingLen)

uint32_t mRemainingLen

mWritePoint

uint8_t * mWritePoint

公開函式

關閉容器

WEAVE_ERROR CloseContainer(
  TLVWriter & containerWriter
)

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

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

當 CloseContainer() 傳回時，應用程式可以繼續使用父項寫入器來寫入出現在容器元素後方的其他 TLV 元素。此時，所提供的容器寫入器應視為 'de-initd'，且在未經重新初始化的情況下才必須使用。

詳細資料
參數
[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 或平台特定錯誤。

繼續處理位元組

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

複製容器

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

複製容器

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

複製容器

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

複製元素

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

複製元素

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

詳細資料
參數
[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 或特定平台的錯誤。

取得容器類型

TLVType GetContainerType(
  void
) const

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

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

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

GetLength 寫入

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
)

初始化要寫入至單一 PacketBuffer 的 TLVWriter 物件。

寫入作業會在提供緩衝區現有資料中的最後一位元組之後開始。

詳細資料
參數
[in] buf
指向 TLV 的 PacketBuffer 指標。
[in] maxLen
應寫入輸出緩衝區的最大位元組數。

Init

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

初始化要寫入至一或多個 PacketBuffers 的 TLVWriter 物件。

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

詳細資料
參數
[in] buf
指向 PLV 資料 (應寫入其中) 的 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
)

初始化一個用來寫入 TLV 容器元素成員的新 TLVWriter 物件。

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

普羅布蘭

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

推桿式

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 容器元素 (結構、陣列或路徑) 進行編碼，其中包含一組從預先編碼緩衝區取得的成員元素。輸入緩衝區預期含有 0 個或更多完整編碼的 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
將 null 終止的 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 或平台特定錯誤。

推桿式

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] ...
依 fmt 輸出輸出值格式的引數清單。
傳回值
WEAVE_NO_ERROR
如果方法成功執行。
other
如果基本呼叫 TLVWriter 方法 WriteElementHead 或 GetNewBuffer 失敗，系統會立即將錯誤錯誤轉送到呼叫堆疊。

起始容器

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

起始輸入位元組數

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 元素的格式格式化字串輸出。

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] ap
依 fmt 輸出輸出值格式的引數清單。
傳回值
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() 函式一起使用。

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

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 類型定義。

取得 NewPacketBuffer

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

TLVWriter GetNewBuffer 函式的實作，可寫入 PacketBuffers 鏈結。

GetNewPacketBuffer() 函式會視需要分配一或多個 PacketBuffers 鏈結來儲存編碼，為 TLVWriter 提供新的輸出空間。這個函式是專為指派給 TLVWriter GetNewBuffer 函式指標所設計。

請注意，搭配 TLVWriter 使用 GetNewPacketBuffer 時，也應使用相對應的 FinalizePacketBuffer() 函式 (或同等值) 來完成緩衝鏈。

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

受保護的函式

關閉容器保留

bool IsCloseContainerReserved(
  void
) const

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

IsContainerOpen

bool IsContainerOpen(
  void
) const

設定關閉容器保留

void SetCloseContainerReserved(
  bool aCloseContainerReserved
)

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

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

寫入資料

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