nl:: Weave:: TLV:: TLVWriter
#include <src/lib/core/WeaveTLV.h>
يتم توفير برنامج ترميز فعّال للذاكرة لكتابة البيانات بتنسيق Weave TLV.
ملخّص
تستخدم TLVWriter برنامج ترميز إلى الأمام فقط وبنمط البث لبيانات Weave TLV. تكتب التطبيقات البيانات إلى أحد الترميزات من خلال استدعاء إحدى طرق Put() للكاتب، وتمرير معلومات العلامة والقيمة المرتبطة بها حسب الضرورة. يمكن للتطبيقات المماثلة ترميز أنواع حاويات TLV (البُنى أو الصفائف أو المسارات) من خلال استدعاء الإجراء OpenContainer() للكاتب أو EnterContainer() .
يمكن لكائن TLVWriter كتابة البيانات مباشرةً إلى مخزن مؤقّت ثابت للمخرجات أو إلى سلسلة مكوّنة من كائن PacketBuffer واحد أو أكثر. بالإضافة إلى ذلك، يمكن للتطبيقات توفير وظيفتَي GetNewBuffer
وFinalizeBuffer
الخاصة بها لتوجيه الإخراج إلى وجهة عشوائية، على سبيل المثال مقبس أو قائمة انتظار خاصة بالأحداث.
الاكتساب
الفئات الفرعية المعروفة المباشرة: nl::Weave::TLV::CircularTLVWriter
الأنواع المحمية |
|
---|---|
@72{
|
تعداد |
الأنواع العلنية |
|
---|---|
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)
|
تكمل كتابة حاوية TLV بعد استدعاء الدالة OpenContainer().
|
ContinuePutBytes(const uint8_t *buf, uint32_t len)
|
لترميز قيمة سلسلة بايت TLV.
|
CopyContainer(TLVReader & container)
|
|
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
لإعداد كائن TLVWriter للكتابة في PacketBuffer واحد.
|
Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)
|
void
لإعداد كائن TLVWriter للكتابة في حزمة PacketBuffers واحدة أو أكثر.
|
InitMalloced(uint8_t *& outBuf, uint32_t initialBufSize, uint32_t maxLen)
|
void
تهيئة كائن TLVWriter للكتابة في مخزن مؤقت ديناميكي.
|
OpenContainer(uint64_t tag, TLVType containerType, TLVWriter & containerWriter)
|
|
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)
|
لترميز قيمة سلسلة UTF8 TLV.
|
PutString(uint64_t tag, const char *buf, uint32_t len)
|
لترميز قيمة سلسلة UTF8 TLV.
|
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 للكتابة في سلسلة من PacketBuffer.
|
GetNewBuffer_Malloced(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)
|
تنفيذ دالة GetNewBuffer TLVWriter للكتابة في مخزن مؤقت ديناميكي.
|
GetNewPacketBuffer(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)
|
يشير ذلك المصطلح إلى تنفيذ دالة GetNewBuffer TLVWriter للكتابة في سلسلة من 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.
يتم استدعاء الدوالّ من هذا النوع عند استدعاء طريقة Finalize() من TLVWriter. يُتوقع أن تنفِّذ الدالة أي تنظيف أو إنهاء لازم يتعلق باستهلاك ناتج كائن writer. ومن الأمثلة على ذلك إجراءات مثل تسجيل الطول النهائي للترميز أو إغلاق واصف ملف.
التفاصيل | |||||||||
---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||
قيم الإرجاع |
|
GetNewBufferFunct
WEAVE_ERROR(* GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen)
دالة تزود مساحة مخزن مؤقت جديدة للمخرجات إلى TLVWriter.
تُستخدم دوال من هذا النوع لإعداد مساحة مخزن مؤقت جديدة لـ TLVWriter للكتابة إليها. عند استدعاء الدالة، من المتوقع أن تُرجع الدالة مؤشرًا إلى موقع الذاكرة الذي يجب كتابة البيانات الجديدة فيه، مع الحد الأقصى لطولها. يمكن للدالة توفير مساحة كتابة إما عن طريق تخصيص مورد احتياطي جديد للاحتفاظ بالبيانات أو عن طريق محو البيانات المكتوبة مسبقًا من المخزن المؤقت الحالي.
التفاصيل | |||||||||
---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||
قيم الإرجاع |
|
السمات العامة
AppData
void * AppData
حقل مؤشر يمكن استخدامه مع البيانات الخاصة بالتطبيق.
FinalizeBuffer
FinalizeBufferFunct FinalizeBuffer
مؤشر يشير إلى دالة سيتم استدعاؤها عند إنهاء TLVWriter.
يستدعي كائن TLVWriter الدالة FinalizeBuffer عند استدعاء طريقة Finalize(). يمكن للتطبيقات ضبط مؤشر الدالة في أي وقت قبل استدعاء Finalize(). ويتم ضبط المؤشر تلقائيًا على NULL، ما يؤدي إلى تجاهل طريقة Finalize() لاستدعاء الدالة.
اطّلِع على تعريف النوع FinalizeBufferFunct للحصول على معلومات إضافية حول تنفيذ دالة FinalizeBuffer.
GetNewBuffer
GetNewBufferFunct GetNewBuffer
مؤشر يشير إلى دالة توفِّر مساحة جديدة للمخزن المؤقت للمخرجات إلى TLVWriter.
يستدعي كائن TLVWriter الدالة GetNewBuffer كلما تمت محاولة لكتابة بيانات تتجاوز حجم المخزن المؤقت الحالي للمخرجات. في حالة التعيين على NULL (القيمة الافتراضية)، سيعرض الكاتب WEAVE_ERROR_NO_MEMORY إذا تجاوزت بيانات الإخراج المخزن المؤقت الحالي.
يمكن تعيين GetNewBuffer بواسطة أحد التطبيقات في أي وقت، ولكن يتم تعيينه عادةً عند تهيئة المؤلف.
راجِع تعريف النوع GetNewBufferFunct للحصول على معلومات إضافية عن تنفيذ دالة GetNewBuffer.
ImplicitProfileId
uint32_t ImplicitProfileId
معرّف الملف الشخصي للعلامات التي يجب ترميزها بشكل ضمني.
عندما يُطلب من كاتب ترميز عنصر جديد، إذا تطابق معرّف الملف الشخصي للعلامة المرتبطة بالعنصر الجديد مع قيمة العضو ImplicitProfileId
، سيشفّر الكاتب العلامة بشكل ضمني، مع حذف معرّف الملف الشخصي في هذه العملية.
يتم ضبط السمة ImplicitProfileId
تلقائيًا على kProfileIdNotSpecified، ما يوجِّه تعليمات إلى الكاتب بعدم إرسال علامات مرمّزة بشكل ضمني. ويمكن للتطبيقات ضبط ImplicitProfileId
في أي وقت لتفعيل علامات الترميز بشكل ضمني بدءًا من النقطة الحالية في الترميز. عادةً ما يعتمد معرف الملف الشخصي المناسب للتعيين على سياق التطبيق أو البروتوكول الذي يتم قوله.
السمات المحمية
mBufHandle
uintptr_t mBufHandle
mBufStart
uint8_t * mBufStart
mContainerType
TLVType mContainerType
mLenWritten
uint32_t mLenWritten
mMaxLen
uint32_t mMaxLen
mRemainingLen
uint32_t mRemainingLen
mWritePoint
uint8_t * mWritePoint
الدوال العامة
CloseContainer
WEAVE_ERROR CloseContainer( TLVWriter & containerWriter )
تكمل كتابة حاوية TLV بعد استدعاء الدالة OpenContainer().
تستعيد طريقة CloseContainer() حالة كائن TLVWriter الرئيسي بعد استدعاء الدالة OpenContainer(). بالنسبة إلى كل استدعاء لـ OpenContainer()، يجب أن تُجري التطبيقات استدعاء OpenContainer() هذا استدعاءً إلى CloseContainer()، مع تمرير مرجع إلى كاتب الحاوية نفسه إلى كلتا الطريقتين.
عند عودة CloseContainer()، يمكن أن تستمر التطبيقات في استخدام الكاتب الرئيسي لكتابة عناصر TLV إضافية تظهر بعد عنصر الحاوية. في هذه المرحلة، يجب اعتبار كاتب الحاوية المزود "غير مهيأ" ويجب عدم استخدامه بدون إعادة التهيئة.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
ContinuePutBytes
WEAVE_ERROR ContinuePutBytes( const uint8_t *buf, uint32_t len )
لترميز قيمة سلسلة بايت TLV.
يجب استخدام هذا الحقل مع StartPutBytes.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
CopyContainer
WEAVE_ERROR CopyContainer( TLVReader & container )
لنسخ عنصر حاوية TLV من الكائن TLVReader.
يعمل CopyContainer() على ترميز عنصر حاوية TLV جديد عن طريق نسخ عنصر حاوية مشفَّر مسبقًا في الموضع الحالي لعنصر TLVReader. تكتب الطريقة عنصر الحاوية الجديد بالكامل في استدعاء واحد، وتنسخ نوع الحاوية وعلامتها وعناصرها من ترميز المصدر. عند عرض الطريقة، يمكن استخدام الكائن writer لكتابة عناصر TLV إضافية بعد عنصر الحاوية.
التفاصيل | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||||||||
قيم الإرجاع |
|
CopyContainer
WEAVE_ERROR CopyContainer( uint64_t tag, TLVReader & container )
لترميز عنصر حاوية TLV من مجموعة مرمّزة مسبقًا من عناصر العضو.
يعمل الإجراء CopyContainer() على ترميز عنصر حاوية TLV جديد (بنية أو مصفوفة أو مسار) يحتوي على مجموعة من العناصر الفرعية مأخوذة من كائن TLVReader. عند استدعاء الطريقة، من المتوقع أن يتم وضع كائن القارئ المُقدّم على عنصر حاوية TLV. سيكون للحاوية التي تم ترميزها حديثًا النوع نفسه وأعضاء حاوية الإدخال نفسها. ويتم تحديد علامة الحاوية الجديدة كمَعلمة إدخال.
عند عرض الطريقة، يمكن استخدام الكائن writer لكتابة عناصر TLV إضافية بعد عنصر الحاوية.
التفاصيل | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||||||||
قيم الإرجاع |
|
CopyContainer
WEAVE_ERROR CopyContainer( uint64_t tag, const uint8_t *encodedContainer, uint16_t encodedContainerLen )
لترميز عنصر حاوية TLV يحتوي على عناصر عضو من حاوية مرمّزة مسبقًا.
يعمل الإجراء CopyContainer() على ترميز عنصر حاوية TLV جديد (بنية أو مصفوفة أو مسار) يحتوي على مجموعة من العناصر الفرعية مأخوذة من محتوى الحاوية المقدَّمة مسبقًا والمشفّرة. عند استدعاء الطريقة، يتم تحليل البيانات في المخزن المؤقت للإدخال الذي تم توفيره كعنصر حاوية TLV، وتتم كتابة حاوية جديدة من النوع نفسه وأعضاء حاوية الإدخال نفسها. ويتم تحديد علامة الحاوية الجديدة كمَعلمة إدخال.
عند عرض الطريقة، يمكن استخدام الكائن writer لكتابة عناصر TLV إضافية بعد عنصر الحاوية.
التفاصيل | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||||||
قيم الإرجاع |
|
CopyElement
WEAVE_ERROR CopyElement( TLVReader & reader )
لنسخ عنصر TLV من كائن القارئ إلى الكاتب.
تشفّر الطريقة CopyElement() عنصر TLV جديد يتم الحصول على نوعه وعلامته وقيمته من كائن TLVReader. عند استدعاء الطريقة، من المتوقّع أن يتم وضع كائن القارئ الذي تم توفيره على عنصر TLV المصدر. سيكون للعنصر الذي تم تشفيره حديثًا نوع وعلامة ومحتويات نفس نوع حاوية الإدخال. إذا كان العنصر المقدّم عبارة عن حاوية TLV (بنية أو مصفوفة أو مسار)، سيتم نسخ محتوى الحاوية بالكامل.
التفاصيل | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||||||||
قيم الإرجاع |
|
CopyElement
WEAVE_ERROR CopyElement( uint64_t tag, TLVReader & reader )
EndContainer
WEAVE_ERROR EndContainer( TLVType outerContainerType )
لإكمال ترميز عنصر حاوية TLV
تكمل الطريقة EndContainer() ترميز عنصر حاوية TLV وتستعيد حالة كائن TLVWrite بعد استدعاء سابق لـ StartContainer(). بالنسبة إلى كل استدعاء لـ StartContainer()، يجب أن تجري تطبيقات StartContainer() استدعاءً مشابهًا إلى EndContainer()، وتمرّر قيمة TLVType التي تعرضها استدعاء StartContainer(). عند إرجاع EndContainer()، يمكن استخدام الكائن writer لكتابة عناصر TLV إضافية تتبع عنصر الحاوية.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
الصياغة النهائية
WEAVE_ERROR Finalize( void )
أكمِل كتابة ترميز TLV.
تُكمل طريقة Finalize() عملية كتابة ترميز TLV في المخزن المؤقت للمخرجات الأساسية. يجب أن يطلب التطبيق الطريقة قبل أن يستخدم محتوى المخزن المؤقت. لا يمكن استدعاء Finalize() إلا في حال عدم توفُّر كاتبي حاويات متاحة للكاتب الحالي. (راجِع OpenContainer()
).
التفاصيل | |||||||
---|---|---|---|---|---|---|---|
قيم الإرجاع |
|
GetContainerType
TLVType GetContainerType( void ) const
تعرض نوع الحاوية التي تتم كتابة TLVWriter بداخلها حاليًا.
تعرض الطريقة GetContainerType() نوع حاوية TLV التي تتم الكتابة داخلها حاليًا TLVWriter. إذا كانت TLVWriter لا تكتب عناصر داخل حاوية (أي إذا كانت الكتابة في المستوى الخارجي من الترميز)، تعرِض الطريقة kTLVType_NotSpecified.
التفاصيل | |
---|---|
المرتجعات |
نوع TLVType للحاوية الحالية أو kTLVType_NotSpecified إذا كان TLVWriter لا يكتب عناصر داخل حاوية.
|
GetLengthWritten
uint32_t GetLengthWritten( void )
تعرض إجمالي عدد وحدات البايت المكتوبة منذ إعداد الكاتب.
التفاصيل | |
---|---|
المرتجعات |
إجمالي عدد وحدات البايت التي تمت كتابتها منذ إعداد المؤلف.
|
إنت
void Init( uint8_t *buf, uint32_t maxLen )
إنت
void Init( PacketBuffer *buf, uint32_t maxLen )
لإعداد كائن TLVWriter للكتابة في PacketBuffer واحد.
تبدأ الكتابة مباشرةً بعد البايت الأخير من البيانات الموجودة في المخزن المؤقت المقدم.
التفاصيل | |||||
---|---|---|---|---|---|
المَعلمات |
|
إنت
void Init( PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers )
لإعداد كائن TLVWriter للكتابة في حزمة PacketBuffers واحدة أو أكثر.
تبدأ الكتابة مباشرةً بعد البايت الأخير من البيانات الموجودة في المخزن المؤقت المحدد. إذا تم ضبط allowDiscontiguousBuffers
على "صحيح"، سيتم تخصيص "حِزم الحزم الإضافية" وربطها بالمخزن المؤقت المُقدَّم حسب الحاجة لاستيعاب كمية البيانات المكتوبة. إذا كان المخزن المؤقت للناتج المحدد هو بالفعل رأس سلسلة مخازن مؤقتة، ستتم كتابة المخرجات إلى الموارد الاحتياطية اللاحقة في السلسلة قبل تخصيص أي مخازن مؤقتة جديدة.
التفاصيل | |||||||
---|---|---|---|---|---|---|---|
المَعلمات |
|
InitMalloced
void InitMalloced( uint8_t *& outBuf, uint32_t initialBufSize, uint32_t maxLen )
تهيئة كائن TLVWriter للكتابة في مخزن مؤقت ديناميكي.
التفاصيل | |||||||
---|---|---|---|---|---|---|---|
المَعلمات |
|
OpenContainer
WEAVE_ERROR OpenContainer( uint64_t tag, TLVType containerType, TLVWriter & containerWriter )
لتهيئة كائن TLVWriter جديد لكتابة أعضاء عنصر حاوية TLV.
وتُستخدم الطريقة OpenContainer() لكتابة عناصر حاوية TLV (البنية أو المصفوفات أو المسارات) إلى أحد الترميزات. تأخذ الطريقة نوع الحاوية الجديدة والعلامة (إن وُجدت) ومرجعًا إلى كائن كاتب جديد (كاتب الحاوية) الذي سيتم إعداده لغرض كتابة عناصر الحاوية. تكتب التطبيقات أعضاء الحاوية الجديدة باستخدام كاتب الحاوية ثم تستدعي CloseContainer() لإكمال ترميز الحاوية.
عندما يكون كاتب الحاوية مفتوحًا، يجب ألا تجري التطبيقات استدعاءات أو تغيّر حالة الكاتب الرئيسي بأي طريقة أخرى.
يكتسب كاتب الحاوية خصائص الإعدادات المختلفة من الكاتب الرئيسي. وهي كما يلي:
- معرّف الملف الشخصي الضمني (ImplicitProfileId)
- مؤشر بيانات التطبيق (AppData)
- مؤشرات الدالة GetNewBuffer وFinalizeBuffer
التفاصيل | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||||
قيم الإرجاع |
|
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int8_t v )
لترميز قيمة عدد صحيح بعلامة TLV.
هذه إحدى وظائف الأعضاء محمّلة بشكل زائد، ويتم توفيرها لتسهيل الاستخدام. تختلف عن الدالة أعلاه فقط في الوسيطة(الوسيطات) التي تقبلها.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int8_t v, bool preserveSize )
لترميز قيمة عدد صحيح بعلامة TLV.
هذه إحدى وظائف الأعضاء محمّلة بشكل زائد، ويتم توفيرها لتسهيل الاستخدام. تختلف عن الدالة أعلاه فقط في الوسيطة(الوسيطات) التي تقبلها.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int16_t v )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int16_t v, bool preserveSize )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int32_t v )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int32_t v, bool preserveSize )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int64_t v )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, int64_t v, bool preserveSize )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, uint8_t v )
لترميز قيمة عدد صحيح غير مُوقَّعة على TLV.
هذه إحدى وظائف الأعضاء محمّلة بشكل زائد، ويتم توفيرها لتسهيل الاستخدام. تختلف عن الدالة أعلاه فقط في الوسيطة(الوسيطات) التي تقبلها.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
وطبِّق
WEAVE_ERROR Put( uint64_t tag, uint8_t v, bool preserveSize )
لترميز قيمة عدد صحيح غير مُوقَّعة على TLV.
هذه إحدى وظائف الأعضاء محمّلة بشكل زائد، ويتم توفيرها لتسهيل الاستخدام. تختلف عن الدالة أعلاه فقط في الوسيطة(الوسيطات) التي تقبلها.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
وطبِّق
WEAVE_ERROR Put( uint64_t tag, uint16_t v )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, uint16_t v, bool preserveSize )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, uint32_t v )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, uint32_t v, bool preserveSize )
وطبِّق
WEAVE_ERROR Put( uint64_t tag, uint64_t v )
وطبِّق
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 )
لترميز قيمة النقطة العائمة TLV.
هذه إحدى وظائف الأعضاء محمّلة بشكل زائد، ويتم توفيرها لتسهيل الاستخدام. تختلف عن الدالة أعلاه فقط في الوسيطة(الوسيطات) التي تقبلها.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
PutBoolean
WEAVE_ERROR PutBoolean( uint64_t tag, bool v )
لترميز القيمة المنطقية TLV.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
PutBytes
WEAVE_ERROR PutBytes( uint64_t tag, const uint8_t *buf, uint32_t len )
لترميز قيمة سلسلة بايت TLV.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
PutNull
WEAVE_ERROR PutNull( uint64_t tag )
لترميز قيمة فارغة TLV.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
PutPreEncodedContainer
WEAVE_ERROR PutPreEncodedContainer( uint64_t tag, TLVType containerType, const uint8_t *data, uint32_t dataLen )
لترميز عنصر حاوية TLV من مجموعة مرمّزة مسبقًا من عناصر العضو.
تعمل الطريقة PutPreEncodedContainer() على ترميز عنصر حاوية TLV جديد (بنية أو مصفوفة أو مسار) يحتوي على مجموعة من عناصر العضوية مأخوذة من مخزن مؤقت مشفَّر مسبقًا. من المتوقّع أن يحتوي المخزن المؤقت للإدخال على عناصر TLV بترميز صفري أو أكثر، مع علامات تتوافق مع القواعد المرتبطة بنوع الحاوية المحدّد (على سبيل المثال، يجب أن يحتوي أعضاء البنية على علامات، ويجب ألّا يحتوي أعضاء المصفوفة على ذلك).
ترمّز الطريقة عنصر الحاوية كاملاً في استدعاء واحد. عند عرض PutPreEncodedContainer()، يمكن استخدام كائن writer لكتابة عناصر TLV إضافية بعد عنصر الحاوية.
التفاصيل | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||||
قيم الإرجاع |
|
PutString
WEAVE_ERROR PutString( uint64_t tag, const char *buf )
لترميز قيمة سلسلة UTF8 TLV.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
PutString
WEAVE_ERROR PutString( uint64_t tag, const char *buf, uint32_t len )
لترميز قيمة سلسلة UTF8 TLV.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
PutStringF
WEAVE_ERROR PutStringF( uint64_t tag, const char *fmt, ... )
يجب ترميز نتيجة السلسلة المنسّقة وفقًا للتنسيق في عنصر TLV.
PutStringF هي تناظرية لدالة sprintf حيث يتم تخزين المخرجات في عنصر TLV بدلاً من مخزن مؤقت للأحرف. عند توفر وظيفة printf الموسعة، يمكن للدالة إخراج سلسلة النتيجة في مساحة تخزين أساسية غير متصلة. يدعم التنفيذ تحسينات printf التالية:
توفّر المنصّة vcbprintf
مستنِدة إلى معاودة الاتصال وتتيح إمكانية طلب معاودة اتصال بدلاً من Puchar.
يوفّر النظام الأساسي صيغة من vsnprintf
تسمى vsnprintf_ex
، وتتوافق هذه السياسة تمامًا مع Vsnprintf باستثناء أنّها تتضمّن شروطًا لحذف أول n
حرف من الإخراج.
تجدر الإشارة إلى أنّه على الرغم من أنّ الدالة المستندة إلى معاودة الاتصال قد تكون الأبسط وتستخدم أقل قدر من الرموز، ستستهلك مجموعة دوال vsprintf_ex
حزمة أقل.
إذا لم يكن أي مما سبق متاحًا ولكن يوفّر النظام الأساسي malloc
، ستخصِّص الدالة مخزنًا مؤقتًا مؤقتًا للاحتفاظ بالمخرجات. عندما لا يوفّر النظام الأساسي أي تحسينات لمجموعة printf أو Marketplace، يتم اقتطاع الناتج بحيث يتناسب مع الحالة المستمرة في وحدة تخزين TLV الحالية
التفاصيل | |||||||
---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||
قيم الإرجاع |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )
بدء ترميز عنصر حاوية TLV جديد
وتُستخدم الطريقة StartContainer() لكتابة عناصر حاوية TLV (البنية أو المصفوفات أو المسارات) إلى أحد الترميزات. تأخذ الطريقة نوع الحاوية الجديدة وعلامتها (إن وُجدت) ومرجعًا لقيمة TLVType التي سيتم استخدامها لحفظ السياق الحالي للكاتب أثناء استخدامه لكتابة الحاوية.
بعد رجوع طريقة StartContainer()، يجب أن يستخدم التطبيق الكائن TLVWriter الحالي لكتابة عناصر الحاوية. عند الانتهاء، يجب أن يستدعي التطبيق الإجراء EndContainer() لإنهاء ترميز الحاوية.
التفاصيل | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||||
قيم الإرجاع |
|
StartPutBytes
WEAVE_ERROR StartPutBytes( uint64_t tag, uint32_t totalLen )
لترميز سلسلة بايت TLV في أجزاء متعدّدة.
يجب استخدام هذا الحقل مع continuePutBytes.
التفاصيل | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||||||||
قيم الإرجاع |
|
VPutStringF
WEAVE_ERROR VPutStringF( uint64_t tag, const char *fmt, va_list ap )
يجب ترميز نتيجة السلسلة المنسّقة وفقًا للتنسيق في عنصر TLV.
PutStringF هي تناظرية لدالة sprintf حيث يتم تخزين المخرجات في عنصر TLV بدلاً من مخزن مؤقت للأحرف. عند توفر وظيفة printf الموسعة، يمكن للدالة إخراج سلسلة النتيجة في مساحة تخزين أساسية غير متصلة. يدعم التنفيذ تحسينات printf التالية:
توفّر المنصّة vcbprintf
مستنِدة إلى معاودة الاتصال وتتيح إمكانية طلب معاودة اتصال بدلاً من Puchar.
يوفّر النظام الأساسي صيغة من vsnprintf
تسمى vsnprintf_ex
، وتتوافق هذه السياسة تمامًا مع Vsnprintf باستثناء أنّها تتضمّن شروطًا لحذف أول n
حرف من الإخراج.
تجدر الإشارة إلى أنّه على الرغم من أنّ الدالة المستندة إلى معاودة الاتصال قد تكون الأبسط وتستخدم أقل قدر من الرموز، ستستهلك مجموعة دوال vsprintf_ex
حزمة أقل.
إذا لم يكن أي مما سبق متاحًا ولكن يوفّر النظام الأساسي malloc
، ستخصِّص الدالة مخزنًا مؤقتًا مؤقتًا للاحتفاظ بالمخرجات. عندما لا يوفّر النظام الأساسي أي تحسينات لمجموعة printf أو Marketplace، يتم اقتطاع الناتج بحيث يتناسب مع الحالة المستمرة في وحدة تخزين TLV الحالية
التفاصيل | |||||||
---|---|---|---|---|---|---|---|
المَعلمات |
|
||||||
قيم الإرجاع |
|
الدوال الثابتة العامة
FinalizePacketBuffer
WEAVE_ERROR FinalizePacketBuffer( TLVWriter & writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t dataLen )
يشير ذلك المصطلح إلى تنفيذ الدالة TLVWriter FinalizeBuffer للكتابة في سلسلة من PacketBuffer.
تنفِّذ الدالة FinalizePacketBuffer() عملية الإنهاء اللازمة عند استخدام TLVWriter للكتابة إلى سلسلة من PacketBuffers. تم تصميم الدالة لاستخدامها بالاقتران مع الدالة GetNewPacketBuffer().
اطّلِع على تعريف نوع FinalizeBufferFunct للحصول على معلومات إضافية عن واجهة برمجة التطبيقات الخاصة بدالة FinalizePacketBuffer().
GetNewBuffer_Malloced
WEAVE_ERROR GetNewBuffer_Malloced( TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen )
تنفيذ دالة GetNewBuffer TLVWriter للكتابة في مخزن مؤقت ديناميكي.
توفّر الدالة GetNewBuffer_Malloced() مساحة إخراج جديدة إلى TLVWriter من خلال مضاعفة حجم المخزن المؤقت الديناميكي الأساسي حسب الحاجة لتخزين الترميز. تم تصميم الدالة ليتم تعيينها إلى مؤشر الدالة GetNewBuffer TLVWriter.
راجِع تعريف النوع GetNewBufferFunct للحصول على معلومات إضافية عن واجهة برمجة التطبيقات لدالة GetNewBuffer_Malloced().
GetNewPacketBuffer
WEAVE_ERROR GetNewPacketBuffer( TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen )
يشير ذلك المصطلح إلى تنفيذ دالة GetNewBuffer TLVWriter للكتابة في سلسلة من PacketBuffers.
توفّر الدالة GetNewPacketBuffer() مساحة إخراج جديدة إلى TLVWriter من خلال تخصيص سلسلة من حزمة PacketBuffer واحدة أو أكثر حسب الحاجة لتخزين الترميز. تم تصميم الدالة ليتم تعيينها إلى مؤشر الدالة GetNewBuffer TLVWriter.
ملاحظة: عند استخدام GetNewPacketBuffer مع TLVWriter، يجب أيضًا استخدام دالة FinalizePacketBuffer() المقابلة (أو ما يعادلها) لإنهاء سلسلة المخزن المؤقت.
راجِع تعريف النوع GetNewBufferFunct للحصول على معلومات إضافية عن واجهة برمجة التطبيقات الخاصة بدالة GetNewPacketBuffer().
الدوال المحمية
IsCloseContainerReserved
bool IsCloseContainerReserved( void ) const
حدد ما إذا كان يجب أن تحجز الحاوية مساحة لرمز CloseContainer عند نقطة بدء / فتح الحاوية.
IsContainerOpen
bool IsContainerOpen( void ) const
SetCloseContainerReserved
void SetCloseContainerReserved( bool aCloseContainerReserved )
اضبط ما إذا كان يجب أن تحتفظ الحاوية بمساحة لرمز CloseContainer عند نقطة بدء / فتح الحاوية.
SetContainerOpen
void SetContainerOpen( bool aContainerOpen )
WriteData
WEAVE_ERROR WriteData( const uint8_t *p, uint32_t len )
WriteElementHead
WEAVE_ERROR WriteElementHead( TLVElementType elemType, uint64_t tag, uint64_t lenOrVal )
WriteElementWithData
WEAVE_ERROR WriteElementWithData( TLVType type, uint64_t tag, const uint8_t *data, uint32_t dataLen )