nl:: Weave:: TLV:: TLVUpdater
#include <src/lib/core/WeaveTLV.h>
มีอินเทอร์เฟซ Reader/Writer แบบรวมสำหรับการแก้ไข/เพิ่ม/ลบองค์ประกอบในการเข้ารหัส TLV
สรุป
TLVUpdater เป็นการรวมออบเจ็กต์ TLVReader และ TLVWriter พร้อมเครื่องมืออินเทอร์เฟซสำหรับแก้ไข/ลบข้อมูลในการเข้ารหัส รวมทั้งเพิ่มองค์ประกอบใหม่ๆ ลงในการเข้ารหัส TLV โดยพื้นฐานแล้ว ออบเจ็กต์ TLVUpdater จะทำหน้าที่เหมือนเคอร์เซอร์ 2 อัน อันหนึ่งสำหรับอ่านการเข้ารหัสที่มีอยู่และอีกอันสำหรับการเขียน (สำหรับการคัดลอกข้อมูลที่มีอยู่หรือการเขียนข้อมูลใหม่)
ในเชิงความหมาย ออบเจ็กต์ TLVUpdater จะทํางานเหมือนการรวมตัวของ TLVReader และ TLVWriter เมธอด TLVUpdater มีความหมายใกล้เคียงกับชื่อที่คล้ายกันใน TLVReader/TLVWriter มากกว่าหรือน้อยลง ซึ่งมีความแตกต่างในความหมาย ความแตกต่างจะระบุไว้อย่างชัดเจนในส่วนความคิดเห็นของฟังก์ชันใน WeaveTLVUpdater.cpp
หมายเหตุสำคัญอย่างหนึ่งเกี่ยวกับเมธอด PutBytes() และ PutString() ของ TLVUpdater ก็คือวิธีการปล่อยให้การเข้ารหัสอยู่ในสถานะเสียหายโดยเขียนเฉพาะส่วนหัวขององค์ประกอบเท่านั้นเมื่อเกิดรายการส่วนเกิน แอปพลิเคชันสามารถเรียก GetRemainingFreeLength() เพื่อให้แน่ใจว่ามีพื้นที่ว่างโดยประมาณสำหรับการเขียนการเข้ารหัส โปรดทราบว่า GetRemainingFreeLength() บอกเฉพาะไบต์ว่างที่มีเท่านั้น และไม่มีวิธีที่แอปพลิเคชันจะทราบความยาวของข้อมูลที่เข้ารหัสที่เขียนขึ้น ในกรณีที่มีรายการเพิ่มเติม ทั้ง PutBytes() และ PutString() จะแสดงผล WEAVE_ERROR_BUFFER_TOO_SMALL ให้กับผู้เรียกใช้
นอกจากนี้ โปรดทราบว่าเมธอด Next() จะทำงานมากเกินไปเพื่อให้ข้ามองค์ประกอบปัจจุบันไปพร้อมๆ กับเลื่อนผู้อ่านภายในไปยังองค์ประกอบถัดไปด้วย เนื่องจากการข้ามองค์ประกอบที่เข้ารหัสไว้แล้วจะต้องมีการเปลี่ยนตัวแปรสถานะพื้นที่ว่างของผู้เขียนภายในเพื่อรองรับพื้นที่ว่างใหม่ (ทำได้ด้วยการข้าม) แอปพลิเคชันจึงควรเรียกใช้ Next() ในโปรแกรมอัปเดตหลังเมธอด Get() ซึ่งไม่ต้องการเขียนกลับ (ซึ่งเทียบเท่ากับการข้ามองค์ประกอบปัจจุบัน)
ฟังก์ชันสาธารณะ |
|
---|---|
CopyElement(TLVReader & reader)
|
|
CopyElement(uint64_t tag, TLVReader & reader)
|
|
DupBytes(uint8_t *& buf, uint32_t & dataLen)
|
|
DupString(char *& buf)
|
|
EndContainer(TLVType outerContainerType)
|
|
EnterContainer(TLVType & outerContainerType)
|
เตรียมออบเจ็กต์ TLVUpdater สำหรับการอ่านองค์ประกอบของคอนเทนเนอร์
|
ExitContainer(TLVType outerContainerType)
|
|
Finalize(void)
|
|
Get(bool & v)
|
|
Get(int8_t & v)
|
|
Get(int16_t & v)
|
|
Get(int32_t & v)
|
|
Get(int64_t & v)
|
|
Get(uint8_t & v)
|
|
Get(uint16_t & v)
|
|
Get(uint32_t & v)
|
|
Get(uint64_t & v)
|
|
Get(float & v)
|
|
Get(double & v)
|
|
GetBytes(uint8_t *buf, uint32_t bufSize)
|
|
GetContainerType(void) const
|
|
GetDataPtr(const uint8_t *& data)
|
|
GetImplicitProfileId(void)
|
uint32_t
|
GetLength(void) const
|
uint32_t
|
GetLengthRead(void) const
|
uint32_t
|
GetLengthWritten(void)
|
uint32_t
|
GetReader(TLVReader & containerReader)
|
void
|
GetRemainingFreeLength(void)
|
uint32_t
|
GetRemainingLength(void) const
|
uint32_t
|
GetString(char *buf, uint32_t bufSize)
|
|
GetTag(void) const
|
uint64_t
|
GetType(void) const
|
|
Init(uint8_t *buf, uint32_t dataLen, uint32_t maxLen)
|
เริ่มต้นออบเจ็กต์ TLVUpdater เพื่อแก้ไขบัฟเฟอร์อินพุตเดียว
|
Init(TLVReader & aReader, uint32_t freeLen)
|
เริ่มต้นออบเจ็กต์ TLVUpdater โดยใช้ TLVReader
|
Move(void)
|
|
MoveUntilEnd(void)
|
void
ย้ายข้อมูลทุกอย่างตั้งแต่จุดอ่านปัจจุบันของ TLVUpdater จนถึงจุดสิ้นสุดของบัฟเฟอร์ TLV ของอินพุตไปยังเอาต์พุต
|
Next(void)
|
ข้ามองค์ประกอบปัจจุบันแล้วเลื่อนออบเจ็กต์ TLVUpdater ไปยังองค์ประกอบถัดไปใน TLV ของอินพุต
|
Put(uint64_t tag, int8_t v)
|
|
Put(uint64_t tag, int16_t v)
|
|
Put(uint64_t tag, int32_t v)
|
|
Put(uint64_t tag, int64_t v)
|
|
Put(uint64_t tag, uint8_t v)
|
|
Put(uint64_t tag, uint16_t v)
|
|
Put(uint64_t tag, uint32_t v)
|
|
Put(uint64_t tag, uint64_t v)
|
|
Put(uint64_t tag, int8_t v, bool preserveSize)
|
|
Put(uint64_t tag, int16_t v, bool preserveSize)
|
|
Put(uint64_t tag, int32_t v, bool preserveSize)
|
|
Put(uint64_t tag, int64_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint8_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint16_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint32_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint64_t v, bool preserveSize)
|
|
Put(uint64_t tag, float v)
|
|
Put(uint64_t tag, double v)
|
|
PutBoolean(uint64_t tag, bool v)
|
|
PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)
|
|
PutNull(uint64_t tag)
|
|
PutString(uint64_t tag, const char *buf)
|
|
PutString(uint64_t tag, const char *buf, uint32_t len)
|
|
SetImplicitProfileId(uint32_t profileId)
|
void
ตั้งรหัสโปรไฟล์แบบไม่เจาะจงปลายทางสำหรับออบเจ็กต์ TLVUpdater
|
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
|
|
VerifyEndOfContainer(void)
|
ฟังก์ชันสาธารณะ
CopyElement
WEAVE_ERROR CopyElement( TLVReader & reader )
CopyElement
WEAVE_ERROR CopyElement( uint64_t tag, TLVReader & reader )
DupBytes
WEAVE_ERROR DupBytes( uint8_t *& buf, uint32_t & dataLen )
DupString
WEAVE_ERROR DupString( char *& buf )
EndContainer
WEAVE_ERROR EndContainer( TLVType outerContainerType )
EnterContainer
WEAVE_ERROR EnterContainer( TLVType & outerContainerType )
เตรียมออบเจ็กต์ TLVUpdater สำหรับการอ่านองค์ประกอบของคอนเทนเนอร์
นอกจากนี้ ยังเข้ารหัสจุดเริ่มต้นของออบเจ็กต์คอนเทนเนอร์ในเอาต์พุต TLV ด้วย
เมธอด EnterContainer() จะเตรียมออบเจ็กต์ TLVUpdater ปัจจุบันเพื่อเริ่มอ่านองค์ประกอบสมาชิกของคอนเทนเนอร์ TLV (โครงสร้าง อาร์เรย์ หรือเส้นทาง) สำหรับทุกการเรียกแอปพลิเคชัน EnterContainer() ต้องเรียก ExitContainer() ที่สอดคล้องกัน
เมื่อเรียก EnterContainer() โปรแกรมอ่านของ TLVUpdater จะต้องวางอยู่บนองค์ประกอบคอนเทนเนอร์ เมธอดนี้ใช้เป็นอาร์กิวเมนต์การอ้างอิงไปยังค่า TLVType ซึ่งจะใช้เพื่อบันทึกบริบทของโปรแกรมอัปเดตขณะที่อ่านคอนเทนเนอร์
เมื่อเมธอด EnterContainer() กลับมา โปรแกรมอัปเดตจะมีตำแหน่งก่อนสมาชิกคนแรกของคอนเทนเนอร์ทันที การเรียก Next() ซ้ำๆ จะเป็นการเลื่อนโปรแกรมอัปเดตผ่านสมาชิกของคอลเล็กชันไปจนกระทั่งถึงปลายทาง ซึ่งโปรแกรมอัปเดตจะแสดง WEAVE_END_OF_TLV
เมื่อแอปพลิเคชันอ่านคอนเทนเนอร์เสร็จแล้ว แอปพลิเคชันจะสามารถอ่านองค์ประกอบต่อไปได้หลังจากคอนเทนเนอร์นั้นด้วยการเรียกใช้เมธอด ExitContainer()
รายละเอียด | |||||||
---|---|---|---|---|---|---|---|
พารามิเตอร์ |
|
||||||
แสดงผลค่า |
|
ExitContainer
WEAVE_ERROR ExitContainer( TLVType outerContainerType )
อ่านองค์ประกอบคอนเทนเนอร์ TLV ให้เสร็จสมบูรณ์และเข้ารหัสการสิ้นสุดขององค์ประกอบ TLV ในเอาต์พุต TLV
เมธอด ExitContainer() คืนค่าสถานะของออบเจ็กต์ TLVUpdater หลังการเรียกไปยัง EnterContainer() ทุกครั้งที่เรียกแอปพลิเคชัน EnterContainer() ต้องเรียกแอปพลิเคชัน ExitContainer() ที่สอดคล้องกัน โดยส่งผ่านค่าบริบทที่แสดงผลโดยเมธอด EnterContainer()
เมื่อ ExitContainer() กลับมา ระบบจะวางเครื่องอ่าน TLVUpdater ก่อนองค์ประกอบแรกที่อยู่ต่อจากคอนเทนเนอร์ใน TLV อินพุต จากจุดนี้ แอปพลิเคชันสามารถเรียก Next() เพื่อเลื่อนผ่านองค์ประกอบอื่นๆ ที่เหลืออยู่ได้
เมื่อเรียก EnterContainer() แล้ว แอปพลิเคชันจะเรียกใช้ ExitContainer() บนตัวอัปเดตได้ทุกเมื่อโดยไม่คำนึงว่ามีการอ่านองค์ประกอบทั้งหมดในคอนเทนเนอร์ที่สําคัญแล้วหรือยัง นอกจากนี้ โปรดทราบว่าการเรียกใช้ ExitContainer() ก่อนอ่านองค์ประกอบทั้งหมดในคอนเทนเนอร์จะส่งผลให้คอนเทนเนอร์ที่อัปเดตแล้วในเอาต์พุต TLV ถูกตัดให้สั้นลง
รายละเอียด | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
พารามิเตอร์ |
|
||||||||||
แสดงผลค่า |
|
ทำให้สิ้นสุด
WEAVE_ERROR Finalize( void )
ดาวน์โหลด
WEAVE_ERROR Get( bool & v )
ดาวน์โหลด
WEAVE_ERROR Get( int8_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( int16_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( int32_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( int64_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( uint8_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( uint16_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( uint32_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( uint64_t & v )
ดาวน์โหลด
WEAVE_ERROR Get( float & v )
ดาวน์โหลด
WEAVE_ERROR Get( double & v )
GetBytes
WEAVE_ERROR GetBytes( uint8_t *buf, uint32_t bufSize )
GetContainerType
TLVType GetContainerType( void ) const
GetDataPtr
WEAVE_ERROR GetDataPtr( const uint8_t *& data )
GetImplicitProfileId
uint32_t GetImplicitProfileId( void )
GetLength
uint32_t GetLength( void ) const
GetLengthRead
uint32_t GetLengthRead( void ) const
GetLengthWritten
uint32_t GetLengthWritten( void )
GetReader
void GetReader( TLVReader & containerReader )
GetRemainingFreeLength
uint32_t GetRemainingFreeLength( void )
GetRemainingLength
uint32_t GetRemainingLength( void ) const
GetString
WEAVE_ERROR GetString( char *buf, uint32_t bufSize )
GetTag
uint64_t GetTag( void ) const
GetType
TLVType GetType( void ) const
เริ่มต้น
WEAVE_ERROR Init( uint8_t *buf, uint32_t dataLen, uint32_t maxLen )
เริ่มต้นออบเจ็กต์ TLVUpdater เพื่อแก้ไขบัฟเฟอร์อินพุตเดียว
เมื่อเรียกใช้เมธอดนี้ ข้อมูล TLV ในบัฟเฟอร์จะย้ายไปอยู่ท้ายบัฟเฟอร์และเริ่มต้นออบเจ็กต์ TLVReader ส่วนตัวในบัฟเฟอร์ที่ย้ายตำแหน่งนี้ ออบเจ็กต์ TLVWriter ส่วนตัวจะเริ่มต้นบนพื้นที่ว่างที่พร้อมใช้งานเมื่อตอนเริ่มต้นด้วยเช่นกัน แอปพลิเคชันสามารถใช้ออบเจ็กต์ TLVUpdater เพื่อแยกวิเคราะห์ข้อมูล TLV และแก้ไข/ลบองค์ประกอบที่มีอยู่ หรือเพิ่มองค์ประกอบใหม่ในการเข้ารหัส
รายละเอียด | |||||||
---|---|---|---|---|---|---|---|
พารามิเตอร์ |
|
||||||
แสดงผลค่า |
|
เริ่มต้น
WEAVE_ERROR Init( TLVReader & aReader, uint32_t freeLen )
เริ่มต้นออบเจ็กต์ TLVUpdater โดยใช้ TLVReader
เมื่อเรียกใช้เมธอดนี้ ระบบจะย้ายข้อมูล TLV ในบัฟเฟอร์ที่ TLVReader ชี้ไปจากจุดอ่านปัจจุบันไปยังจุดสิ้นสุดของบัฟเฟอร์ ออบเจ็กต์ TLVReader ส่วนตัวใหม่จะได้รับการเริ่มต้นให้อ่านจากตำแหน่งใหม่นี้ ขณะที่ออบเจ็กต์ TLVWriter ส่วนตัวแบบใหม่จะได้รับการเริ่มต้นให้เขียนไปยังพื้นที่บัฟเฟอร์ที่เพิ่มพื้นที่ว่าง
โปรดทราบว่าหาก TLVReader อยู่ในตำแหน่ง "on" แล้ว องค์ประกอบจะถอยหลังไปยังจุดเริ่มต้นขององค์ประกอบนั้นก่อน นอกจากนี้ โปรดทราบว่าการสำรองข้อมูลนี้ใช้ได้ดีกับองค์ประกอบคอนเทนเนอร์ กล่าวคือ หากใช้ TLVReader เพื่อเรียกใช้ EnterContainer() แล้วก็จะไม่มีการย้อนกลับ แต่หากมีการวาง TLVReader ในองค์ประกอบคอนเทนเนอร์และยังไม่มีการเรียกใช้ EnterContainer() ระบบจะเลื่อนออบเจ็กต์ TLVReader ไปที่จุดเริ่มต้นของคอนเทนเนอร์
ออบเจ็กต์ TLVReader จะถูกทำลายก่อนแสดงผลและแอปพลิเคชันต้องไม่ใช้สิ่งเดียวกันนี้เมื่อส่งคืน
รายละเอียด | |||||||
---|---|---|---|---|---|---|---|
พารามิเตอร์ |
|
||||||
แสดงผลค่า |
|
ย้าย
WEAVE_ERROR Move( void )
คัดลอกองค์ประกอบปัจจุบันจากอินพุต TLV ไปยังเอาต์พุต TLV
เมธอด Move() จะคัดลอกองค์ประกอบปัจจุบันที่มีการวางตำแหน่งเครื่องอ่านของ TLVUpdater ไปยังผู้เขียนของ TLVUpdater แอปพลิเคชันควรเรียก Next() และวางตำแหน่งโปรแกรมอ่านของ TLVUpdater บนองค์ประกอบก่อนเรียกใช้เมธอดนี้ เช่นเดียวกับเมธอด TLVReader::Next() หากผู้อ่านอยู่ในตำแหน่งขององค์ประกอบคอนเทนเนอร์ในขณะที่มีการเรียกใช้ ระบบจะคัดลอกสมาชิกทั้งหมดของคอนเทนเนอร์ หากเครื่องอ่านไม่ได้อยู่ในองค์ประกอบใดองค์ประกอบหนึ่ง ก็จะไม่มีการเปลี่ยนแปลงเมื่อเรียกใช้เมธอดนี้
รายละเอียด | |||||||||
---|---|---|---|---|---|---|---|---|---|
แสดงผลค่า |
|
MoveUntilEnd
void MoveUntilEnd( void )
ย้ายข้อมูลทุกอย่างตั้งแต่จุดอ่านปัจจุบันของ TLVUpdater จนถึงจุดสิ้นสุดของบัฟเฟอร์ TLV ของอินพุตไปยังเอาต์พุต
วิธีนี้รองรับการย้ายทุกอย่างตั้งแต่จุดอ่านปัจจุบันของ TLVUpdater จนถึงจุดสิ้นสุดของบัฟเฟอร์เครื่องอ่านไปยังผู้เขียนของ TLVUpdater
ถัดไป
WEAVE_ERROR Next( void )
ข้ามองค์ประกอบปัจจุบันแล้วเลื่อนออบเจ็กต์ TLVUpdater ไปยังองค์ประกอบถัดไปใน TLV ของอินพุต
เมธอด Next() จะข้ามองค์ประกอบปัจจุบันใน TLV ของอินพุต และเลื่อนโปรแกรมอ่านของ TLVUpdater ไปยังองค์ประกอบถัดไปที่อยู่ในบริบทการบรรจุเดียวกัน โดยเฉพาะอย่างยิ่ง หากเครื่องอ่านอยู่ในตำแหน่งที่อยู่ระดับนอกสุดของการเข้ารหัส TLV การเรียก Next() จะเลื่อนไปยังองค์ประกอบที่อยู่บนสุดลำดับถัดไป หากวางเครื่องอ่านภายในองค์ประกอบคอนเทนเนอร์ TLV (โครงสร้าง อาร์เรย์ หรือเส้นทาง) การเรียกใช้ Next() จะเลื่อนไปยังองค์ประกอบสมาชิกถัดไปของคอนเทนเนอร์
เนื่องจาก Next() จะบังคับการเคลื่อนไหวของผู้อ่านไปยังบริบทการบรรจุปัจจุบัน การเรียกใช้ Next() เมื่อจัดตำแหน่งผู้อ่านบนองค์ประกอบคอนเทนเนอร์จะเลื่อนไปข้างหน้าเหนือคอนเทนเนอร์ โดยจะข้ามองค์ประกอบสมาชิก (และสมาชิกของคอนเทนเนอร์ที่ซ้อนอยู่ทั้งหมด) ไปจนกระทั่งถึงองค์ประกอบแรกหลังคอนเทนเนอร์
เมื่อไม่มีองค์ประกอบเพิ่มเติมภายในบริบทการรวมหนึ่งๆ เมธอด Next() จะแสดงข้อผิดพลาด WEAVE_END_OF_TLV และตำแหน่งเครื่องอ่านจะไม่เปลี่ยนแปลง
รายละเอียด | |||||
---|---|---|---|---|---|
แสดงผลค่า |
|
วาง
WEAVE_ERROR Put( uint64_t tag, int8_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, int16_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, int32_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, int64_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, uint8_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, uint16_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, uint32_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, uint64_t v )
วาง
WEAVE_ERROR Put( uint64_t tag, int8_t v, bool preserveSize )
วาง
WEAVE_ERROR Put( uint64_t tag, int16_t v, bool preserveSize )
วาง
WEAVE_ERROR Put( uint64_t tag, int32_t v, bool preserveSize )
วาง
WEAVE_ERROR Put( uint64_t tag, int64_t v, bool preserveSize )
วาง
WEAVE_ERROR Put( uint64_t tag, uint8_t v, bool preserveSize )
วาง
WEAVE_ERROR Put( uint64_t tag, uint16_t v, bool preserveSize )
วาง
WEAVE_ERROR Put( uint64_t tag, uint32_t v, bool preserveSize )
วาง
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 )
PutBoolean
WEAVE_ERROR PutBoolean( uint64_t tag, bool v )
PutBytes
WEAVE_ERROR PutBytes( uint64_t tag, const uint8_t *buf, uint32_t len )
PutNull
WEAVE_ERROR PutNull( uint64_t tag )
PutString
WEAVE_ERROR PutString( uint64_t tag, const char *buf )
PutString
WEAVE_ERROR PutString( uint64_t tag, const char *buf, uint32_t len )
SetImplicitProfileId
void SetImplicitProfileId( uint32_t profileId )
ตั้งรหัสโปรไฟล์แบบไม่เจาะจงปลายทางสำหรับออบเจ็กต์ TLVUpdater
เมธอดนี้จะกำหนดรหัสโปรไฟล์โดยนัยสำหรับออบเจ็กต์ TLVUpdater เมื่อมีการขอให้โปรแกรมอัปเดตเข้ารหัสองค์ประกอบใหม่ หากรหัสโปรไฟล์ของแท็กที่เชื่อมโยงกับองค์ประกอบใหม่ตรงกับค่าของ profileId
โปรแกรมอัปเดตจะเข้ารหัสแท็กในรูปแบบโดยนัย โดยจะไม่ใส่รหัสโปรไฟล์ในขั้นตอนนี้
รายละเอียด | |||
---|---|---|---|
พารามิเตอร์ |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )