nl::Weave::TLV::TLVUpdater

#include <src/lib/core/WeaveTLV.h>

يوفر واجهة قارئ/كاتب موحدة لتعديل/إضافة/حذف العناصر بترميز TLV.

ملخّص

يعد TLVUpdater اتحادًا بين الكائنات TLVReader وTLVWriter ويوفر طرقًا للواجهة لتعديل/حذف البيانات في الترميز فضلاً عن إضافة عناصر جديدة إلى ترميز TLV. يعمل الكائن TLVUpdater بشكل أساسي كمؤشرين، أحدهما لقراءة الترميز الحالي والآخر للكتابة (إما لنسخ البيانات الحالية أو كتابة بيانات جديدة).

دلاليًا، يعمل الكائن 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)
لإكمال قراءة عنصر حاوية 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
اضبط رقم تعريف الملف الشخصي الضمني للعنصر 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().

التفاصيل
المَعلمات
[out] outerContainerType
يشير إلى قيمة TLVType التي سيتلقّى سياق أداة التعديل.
قيم الإرجاع
WEAVE_NO_ERROR
إذا نجحت الطريقة.
WEAVE_ERROR_INCORRECT_STATE
في حال عدم وضع قارئ TLVUpdater في عنصر حاوية.
other
أي رمز خطأ آخر في Weave أو Platform يعرضه TLVWriter::StartContainer() أو TLVReader::EnterContainer().

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

لإكمال قراءة عنصر حاوية TLV وترميز نهاية عنصر TLV في TLV الإخراج.

تستعيد طريقة 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

إنت

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
إذا كان المخزن المؤقت صغيرًا جدًا.

إنت

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

إعداد كائن TLVUpdater باستخدام TLVReader.

عند استدعاء هذه الطريقة، يتم نقل بيانات TLV في المخزن المؤقت المشار إليه بواسطة TLVReader من نقطة القراءة الحالية إلى نهاية المخزن المؤقت. يتم إعداد كائن TLVReader خاص جديد للقراءة من هذا الموضع الجديد، بينما يتم إعداد كائن TLVWriter خاص جديد للكتابة في مساحة المخزن المؤقت التي تم إخلاء جزء منها.

تجدر الإشارة إلى أنّه في حال ضبط TLVReader على عنصر معيّن مسبقًا، سيتم أولاً إيقاف هذا العنصر في بداية هذا العنصر. وتجدر الإشارة أيضًا إلى أنّ ميزة "التراجع" هذه تعمل بشكل جيد مع عناصر الحاوية، بمعنى أنّه إذا تم استخدام TLVReader لاستدعاء EnterContainer()، ليس هناك ما يمكن التراجع عنه، ولكن في حال عدم وضع TLVReader في عنصر الحاوية ولم يتم استدعاء EnterContainer() بعد، سيتم إنشاء نسخة احتياطية من الكائن TLVReader عند بدء تشغيل الحاوية.

سيتم إتلاف الكائن 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 على أحد العناصر قبل استدعاء هذه الطريقة. تمامًا كما هو الحال في الإجراء TLVReader::Next()، إذا تم وضع القارئ في عنصر حاوية في وقت الاستدعاء، سيتم نسخ جميع أعضاء الحاوية. إذا لم يكن القارئ في موضعه على أي عنصر، فلن يتغير شيء عند استدعاء هذه الطريقة.

التفاصيل
قيم الإرجاع
WEAVE_NO_ERROR
في حال وضع قارئ TLVUpdater بنجاح على عنصر جديد
WEAVE_END_OF_TLV
في حال كان قارئ TLVUpdater يشير إلى نهاية الحاوية.
WEAVE_ERROR_INVALID_TLV_ELEMENT
في حال عدم وضع قارئ جهاز TLVIpdater على عنصر TLV صالح
other
لعرض رموز الخطأ الأخرى التي تعرضها طريقة TLVReader::تخطي().

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_NO_ERROR
في حال وضع قارئ TLVUpdater بنجاح على عنصر جديد
other
تعرض رموز الخطأ Weave أو النظام الأساسي التي تعرضها الطريقة TLVReader::سجل() و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
)

اضبط رقم تعريف الملف الشخصي الضمني للعنصر TLVUpdater.

تضبط هذه الطريقة رقم تعريف الملف الشخصي الضمني للعنصر TLVUpdater. عندما يُطلب من أداة التحديث ترميز عنصر جديد، وإذا تطابق رقم تعريف الملف الشخصي للعلامة المرتبطة بالعنصر الجديد مع قيمة profileId، ستشفّر أداة التحديث العلامة بشكل ضمني، وبالتالي سيتم حذف رقم تعريف الملف الشخصي في العملية.

التفاصيل
المَعلمات
[in] profileId
معرّف الملف الشخصي للعلامات التي يجب ترميزها بشكل ضمني.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)