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)
הפונקציה משלימה את הקריאה של רכיב קונטיינר TLV ומקודדת את סוף רכיב TLV בפלט TLV.
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)
מעתיק את הרכיב הנוכחי מהקלט TLV לפלט TLV.
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().

פרטים
פרמטרים
[out] outerContainerType
הפניה לערך TLVType שיקבל את ההקשר של המעדכן.
מוחזר ערכים
WEAVE_NO_ERROR
אם השיטה הצליחה.
WEAVE_ERROR_INCORRECT_STATE
אם הקורא של TLVUpdater לא ממוקם על רכיב של קונטיינר.
other
כל קוד שגיאה אחר של Weave או פלטפורמה שהוחזר על ידי TLVWriter::StartContainer() או TLVReader::EnterContainer().

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

הפונקציה משלימה את הקריאה של רכיב קונטיינר TLV ומקודדת את סוף רכיב TLV בפלט TLV.

ה-method ExitContainer() משחזר את המצב של אובייקט TLVUpdater אחרי קריאה ל-EnterContainer(). בכל קריאה לאפליקציות EnterContainer() צריך לבצע קריאה תואמת ל-ExitContainer(), ומעביר את ערך ההקשר שמוחזר על ידי המתודה EnterContainer().

כש-ExitContainer() חוזר, הקורא TLVUpdater ממוקם ממש לפני הרכיב הראשון שאחרי הקונטיינר בקלט TLV. מנקודה זו אפליקציות יכולות לקרוא ל-Next() כדי להתקדם דרך כל האלמנטים שנותרו.

לאחר הקריאה ל-EnterContainer(), אפליקציות יכולות לקרוא ל-ExitContainer() בכלי המעדכן בכל שלב, גם אם כל הרכיבים בקונטיינר הבסיסי נקראו. כמו כן, חשוב לשים לב שקריאה ל-ExitContainer() לפני קריאה של כל הרכיבים בקונטיינר, תגרום לחיתוך של הקונטיינר המעודכן בפלט TLV.

פרטים
פרמטרים
[in] outerContainerType
ערך TLVType שהוחזר באמצעות שיטת EnterContainer().
מוחזר ערכים
WEAVE_NO_ERROR
אם השיטה הצליחה.
WEAVE_ERROR_TLV_UNDERRUN
אם הקידוד הבסיסי של ה-TLV הסתיים מוקדם מדי.
WEAVE_ERROR_INVALID_TLV_ELEMENT
אם המעדכן נתקל בסוג רכיב TLV לא חוקי או לא נתמך.
WEAVE_ERROR_INVALID_TLV_TAG
אם המעדכן נתקל בתג TLV בהקשר לא חוקי.
other
כל קוד שגיאה אחר של Weave או פלטפורמה שהוחזר על ידי TLVWriter::EndContainer() או TLVReader::ExitContainer().

סיום

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 ולשנות/למחוק רכיבים קיימים, או להוסיף רכיבים חדשים לקידוד.

פרטים
פרמטרים
[in] buf
מצביע למאגר נתונים זמני שמכיל את נתוני TLV לעריכה.
[in] dataLen
אורך נתוני TLV במאגר הנתונים הזמני.
[in] maxLen
האורך הכולל של מאגר הנתונים הזמני.
מוחזר ערכים
WEAVE_NO_ERROR
אם השיטה הצליחה.
WEAVE_ERROR_INVALID_ARGUMENT
אם הכתובת של מאגר הנתונים הזמני לא תקינה.
WEAVE_ERROR_BUFFER_TOO_SMALL
אם מאגר הנתונים הזמני קטן מדי.

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 יושמד לפני החזרה ואסור לאפליקציה להשתמש בו בהחזרה.

פרטים
פרמטרים
[in,out] aReader
הפניה לאובייקט TLVReader שיושמד לפני החזרה.
[in] freeLen
האורך של המקום הפנוי (בבייטים) שזמין במאגר הנתונים המקודד מראש.
מוחזר ערכים
WEAVE_NO_ERROR
אם השיטה הצליחה.
WEAVE_ERROR_INVALID_ARGUMENT
אם הכתובת של מאגר הנתונים הזמני לא תקינה.
WEAVE_ERROR_NOT_IMPLEMENTED
אם הקורא הופעל בשרשרת של מאגרי נתונים זמניים.

העברה

WEAVE_ERROR Move(
  void
)

מעתיק את הרכיב הנוכחי מהקלט TLV לפלט TLV.

שיטת Move() מעתיקה את הרכיב הנוכחי שעליו ממוקם הקורא של TLVUpdater, לכותב של TLVUpdater. האפליקציה צריכה לקרוא ל-Next() ולמקם את הקורא של TLVUpdater על רכיב לפני הקריאה ל-method הזה. בדיוק כמו בשיטה TLVReader::Next(), אם הקורא ממוקם על רכיב קונטיינר בזמן הקריאה, כל הרכיבים של המאגר יועתקו. אם הקורא לא ממוקם על רכיב כלשהו, לא יהיה שינוי בהפעלת השיטה הזו.

פרטים
מוחזר ערכים
WEAVE_NO_ERROR
אם הקורא של TLVUpdater הוצב בהצלחה על רכיב חדש.
WEAVE_END_OF_TLV
אם הקורא של TLVUpdater מפנה אל קצה המאגר.
WEAVE_ERROR_INVALID_TLV_ELEMENT
אם הקורא של ה-TLVIpdater לא ממוקם על רכיב TLV חוקי.
other
מחזירה קודי שגיאה אחרים שהוחזרו באמצעות שיטת TLVReader::Skip().

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_NO_ERROR
אם הקורא של TLVUpdater הוצב בהצלחה על רכיב חדש.
other
מחזירה את קודי השגיאה של Weave או הפלטפורמה שהוחזרו על ידי המתודה TLVReader::Skip() ו-TLVReader::Next().

מיקום

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, המעדכן יקודד את התג בצורה משתמעת וכך להשמיט את מזהה הפרופיל.

פרטים
פרמטרים
[in] profileId
מזהה הפרופיל של התגים שצריך לקודד בצורה משתמעת.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)