nl:: Weave:: TLV:: TLVUpdater
#include <src/lib/core/WeaveTLV.h>
ממשק מאוחד של Reader/Writer לעריכה, להוספה או למחיקה של רכיבים בקידוד TLV.
סיכום
ה-TLVUpdater הוא איחוד של האובייקטים TLVReader ו-TLVWriter ומספק שיטות ממשק לעריכה/מחיקה של נתונים בקידוד וגם להוספת רכיבים חדשים לקידוד TLV. אובייקט TLVUpdater פועל בעצם כשני סמנים, אחד לקריאת קידוד קיים ואחד לכתיבה (להעתקה על נתונים קיימים או לכתיבת נתונים חדשים).
מבחינה סמנטית, האובייקט TLVUpdater פועל כמו איחוד של TLVReader ו-TLVWriter. ל-methods של TLVUpdater יש משמעויות דומות יותר או פחות כמו מקבילות ב-TLVReader/TLVWriter. במקרים שבהם יש הבדלים בסמנטיקה, ההבדלים האלה מתועדים בבירור בקטע התגובות של הפונקציה ב-WeaveTLVUpdater.cpp.
הערה חשובה במיוחד לגבי שיטות PutBytes() ו-putString() של TLVUpdater היא שהיא יכולה להשאיר את הקידוד במצב פגום, כאשר רק כותרת הרכיב נכתבת כאשר מתרחשת גלישה. האפליקציות יכולות לקרוא ל-Get leftFreeLength() כדי לוודא שיש מספיק מקום פנוי בערך כדי לכתוב את הקידוד. חשוב לשים לב ש-GetKeepFreeLength() מציין רק את הבייטים הזמינים בחינם ואין לאפליקציה דרך לדעת את אורך הנתונים המקודדים שנכתבים. במקרה של גלישה עודפת, גם PutBytes() ו-PutString() יחזירו WEAVE_ERROR_BUFFER_TOO_PENDING לפונקציית הקריאה.
כמו כן, חשוב לשים לב ששיטת 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
מגדירים את מזהה הפרופיל ה-Implicit של האובייקט 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.
ה-method EnterContainer() מכינה את אובייקט TLVUpdater הנוכחי כך שיתחיל לקרוא את הרכיבים החברים בקונטיינר TLV (מבנה, מערך או נתיב). בכל קריאה ל-EnterContainer(), חייבים לבצע קריאה תואמת ל-ExitContainer().
כשקוראים לפונקציה EnterContainer(), הקורא של TLVUpdater חייב להיות ממוקם על רכיב הקונטיינר. השיטה הזו משתמשת כארגומנט כהפניה לערך TLVType שישמשו לשמירת ההקשר של המעדכן בזמן קריאת הקונטיינר.
כשהשיטה EnterContainer() חוזרת, המעדכן ממוקם ממש לפני האיבר הראשון בקונטיינר. קריאה חוזרת ל-Next() תקדם את המעדכן דרך חברי האוסף עד למועד הסיום, ואז המעדכן יחזיר WEAVE_END_OF_TLV.
לאחר שהאפליקציה מסיימת לקרוא קונטיינר, היא יכולה להמשיך לקרוא את הרכיבים אחרי הקונטיינר על ידי קריאה לשיטה ExitContainer().
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
מוחזר ערכים |
|
ExitContainer
WEAVE_ERROR ExitContainer( TLVType outerContainerType )
הפונקציה משלימה את הקריאה של רכיב קונטיינר TLV ומקודדת את סוף רכיב TLV בפלט TLV.
ה-method 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
Init
WEAVE_ERROR Init( uint8_t *buf, uint32_t dataLen, uint32_t maxLen )
מאתחלים אובייקט TLVUpdater כדי לערוך מאגר נתונים זמני של קלט.
כשמפעילים את השיטה הזו, נתוני TLV במאגר הנתונים הזמני מועברים לסוף החוצץ ואובייקט TLVReader פרטי מופעל במאגר הנתונים הזמני. אובייקט TLVWriter פרטי מאותחל גם במקום הפנוי שזמין בהתחלה. האפליקציות יכולות להשתמש באובייקט TLVUpdater כדי לנתח את נתוני TLV ולשנות/למחוק רכיבים קיימים, או להוסיף רכיבים חדשים לקידוד.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
מוחזר ערכים |
|
Init
WEAVE_ERROR Init( TLVReader & aReader, uint32_t freeLen )
מאתחלים אובייקט TLVUpdater באמצעות TLVReader.
בהפעלה של השיטה הזו, נתוני TLV במאגר הנתונים הזמני שאליו ה-TLVReader מצביעים עוברים מנקודת הקריאה הנוכחית לסוף החוצץ. אובייקט TLVReader פרטי חדש מאותחל לקריאה מהמיקום החדש, ואובייקט TLVWriter פרטי חדש מאותחל לכתיבה לאזור האחסון הזמני שהתפנה.
שימו לב שאם TLVReader כבר נמצא במצב 'on'. רכיב, הוא מגובה תחילה לתחילת הרכיב הזה. כמו כן, חשוב לזכור שהגיבוי הזה פועל היטב עם רכיבי קונטיינרים, כלומר אם TLVReader כבר שימש לקריאה ל-EnterContainer(), אז אין שום דבר שצריך לבצע לפני ניסיון חוזר (backoff). אבל אם ה-TLVReader היה ממוקם על רכיב הקונטיינר ועדיין לא בוצעה קריאה ל-EnterContainer(), אז האובייקט TLVReader מגובה לתחילת ה-head של הקונטיינר.
אובייקט הקלט TLVReader יושמד לפני החזרה ואסור לאפליקציה להשתמש בו בהחזרה.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
מוחזר ערכים |
|
העברה
WEAVE_ERROR Move( void )
מעתיק את הרכיב הנוכחי מהקלט TLV לפלט TLV.
שיטת Move() מעתיקה את הרכיב הנוכחי שעליו ממוקם הקורא של TLVUpdater, לכותב של TLVUpdater. האפליקציה צריכה לקרוא ל-Next() ולמקם את הקורא של TLVUpdater על רכיב לפני הקריאה ל-method הזה. בדיוק כמו בשיטה TLVReader::Next(), אם הקורא ממוקם על רכיב קונטיינר בזמן הקריאה, כל הרכיבים של המאגר יועתקו. אם הקורא לא ממוקם על רכיב כלשהו, לא יהיה שינוי בהפעלת השיטה הזו.
פרטים | |||||||||
---|---|---|---|---|---|---|---|---|---|
מוחזר ערכים |
|
MoveUntilEnd
void MoveUntilEnd( void )
מעבירים את כל הנתונים מנקודת הקריאה הנוכחית של TLVUpdater עד לסוף של מאגר הנתונים הזמני TLV למעבר לפלט.
בשיטה הזו אפשר להעביר את כל הנתונים מנקודת הקריאה הנוכחית של TLVUpdater עד לסוף מאגר הנתונים הזמני של הקוראים, אל הכותב של TLVUpdater.
הבא
WEAVE_ERROR Next( void )
מדלגים על הרכיב הנוכחי ומעבירים את האובייקט TLVUpdater לרכיב הבא בקלט TLV.
ה-method Next() מדלגת על הרכיב הנוכחי בקלט TLV ומקדמת את הקורא של TLVUpdater לרכיב הבא שנמצא באותו הקשר של גבולות. באופן ספציפי, אם הקורא נמצא ברמה החיצונית ביותר של קידוד TLV, קריאה ל-Next() תקדם אותו לאלמנט הבא, העליון ביותר. אם הקורא ממוקם בתוך רכיב קונטיינר TLV (מבנה, מערך או נתיב), קריאה ל-Next() תקדם אותו לאלמנט החבר הבא של הקונטיינר.
מכיוון ש-Next() מגבילה את תנועת הקורא להקשר הבלימת הנוכחי, קריאה ל-Next() כשהקורא ממוקם על רכיב בקונטיינר תקדם מעל הקונטיינר וידלג על הרכיבים שכלולים בו (ועל הרכיבים של קונטיינרים בתוך קונטיינרים) עד שהוא יגיע לאלמנט הראשון אחרי הקונטיינר.
כשאין רכיבים נוספים בתוך הקשר מסוים של הגבלה, ה-method 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 )
מגדירים את מזהה הפרופיל ה-Implicit של האובייקט TLVUpdater.
השיטה הזו מגדירה את מזהה הפרופיל המשתמע של האובייקט TLVUpdater. כשהמעדכן מתבקש לקודד רכיב חדש, אם מזהה הפרופיל של התג שמשויך לרכיב החדש תואם לערך של profileId
, המעדכן יקודד את התג בצורה משתמעת וכך להשמיט את מזהה הפרופיל.
פרטים | |||
---|---|---|---|
פרמטרים |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )