nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

فئة المخزن المؤقت للحزم هي البنية الأساسية المستخدمة لمعالجة حزم البيانات المتسلسلة ثماني بتات، عادة في سياق شبكة اتصالات البيانات، مثل البلوتوث أو بروتوكول الإنترنت.

ملخّص

وفي البيئات التي تستند إلى LwIP، يتم إنشاء هذه الفئة أعلى بنية pbuf المحددة في تلك المكتبة. في حال عدم وجود LwIP، يوفر Weave إما تطبيقًا يعتمد على تطوير البرامج (Maloc) أو تنفيذًا يستند إلى مجموعة البيانات التي تعمل على تجميع البيانات يقترب بشكل وثيق من تحديات الذاكرة التي تواجه الأجهزة المضمّنة بشكل كبير.

إنّ فئة PacketBuffer، مثل العديد من البنى المتشابهة المستخدَمة في حِزم الشبكات المتعدّدة الطبقات، توفّر آلية لحجز مساحة لرؤوس البروتوكولات في كل طبقة من طبقات حزمة الاتصال القابلة للضبط. لمعرفة التفاصيل، يمكنك الاطّلاع على PacketBuffer::New() بالإضافة إلى مستندات LwIP.

يتم إحصاء كائنات PacketBuffer كمرجع، ووضع الاستخدام السائد في Weave هو "fire-and-get". أثناء إرسال الحزمة (وكائن PacketBuffer الكامن الخاص بها) عبر طبقات بروتوكول مختلفة، يشير نجاح طلب أو اعتراض بين الطبقات إلى نقل الملكية، ويكون المُستدعٍ مسؤولاً عن إخلاء المخزن المؤقت. عند فشل الاتصال عبر الطبقات، يتحمل المتصل مسؤولية تحرير المورد الاحتياطي.

يتم إعداد العناصر الجديدة لفئة PacketBuffer في بداية تخصيص الذاكرة التي يتم الحصول عليها من البيئة الأساسية، على سبيل المثال. من مجموعات استهداف LwIP pbuf، من كومة مكتبة C القياسية، من مجمع مخزن مؤقت داخلي. في الحالة البسيطة، يكون حجم المخزن المؤقت للبيانات WEAVE_SYSTEM_PACKETBUFFER_SIZE. يتم توفير المؤلف الذي يسمح باستخدام المخازن المؤقتة للبيانات بأحجام أخرى.

يمكن ربط كائنات PacketBuffer بالتسلسل لاستيعاب الأحمال الكبيرة. ومع ذلك، فإن التسلسل ليس شفافًا، ويجب على مستخدمي هذه الفئة أن يقرروا صراحةً دعم التسلسل. في ما يلي أمثلة على الصفوف المكتوبة باستخدام السلاسل النصية: 

@ref nl::Weave::WeaveTLVReader
@ref nl::Weave::WeaveTLVWriter

الاكتساب

يتم الاكتساب من: pbuf

وظائف عامة
AddRef(void)
void
يجب زيادة عدد المراجع للمخزن المؤقت الحالي.
AddToEnd(PacketBuffer *aPacket)
void
أضف المخزن المؤقت للحزمة المحدد إلى نهاية سلسلة المخزن المؤقت، مع ضبط إجمالي طول كل مورد احتياطي في السلسلة وفقًا لذلك.
AlignPayload(uint16_t aAlignBytes)
bool
محاذاة حمولة بيانات المخزن المؤقت على حدود البايت المحددة
AllocSize(void) const
size_t
عرض حجم التخصيص بما في ذلك مساحات البيانات المحجوزة والحمولة، ولكن بدون تضمين المساحة المخصصة لبنية PacketBuffer
AvailableDataLength(void) const
uint16_t
احصل على عدد وحدات بايت البيانات التي يمكن إضافتها إلى المخزن المؤقت الحالي استنادًا إلى موضع البدء الحالي وطول البيانات.
CompactHead(void)
void
نقل البيانات من المخازن المؤقتة اللاحقة في السلسلة إلى المخزن المؤقت الحالي حتى تمتلئ.
Consume(uint16_t aConsumeLength)
تستهلك البيانات في سلسلة من الموارد الاحتياطية.
ConsumeHead(uint16_t aConsumeLength)
void
قم بضبط المخزن المؤقت الحالي للإشارة إلى كمية البيانات المستهلكة.
DataLength(void) const
uint16_t
الحصول على طول البيانات بالبايت في المخزن المؤقت للحزم
DetachTail(void)
فصل المورد الاحتياطي الحالي من سلسلته وإعادة مؤشر إلى الموارد الاحتياطية المتبقية.
EnsureReservedSize(uint16_t aReservedSize)
bool
تأكد من أن المورد الاحتياطي يحتوي على الأقل على القدر المحدد من المساحة المحجوزة.
MaxDataLength(void) const
uint16_t
الحصول على الحد الأقصى، بالبايت، من البيانات التي تلائم المخزن المؤقت وفقًا لموضع البدء الحالي وحجم المخزن المؤقت.
Next(void) const
الحصول على مؤشر إلى المورد الاحتياطي التالي في السلسلة
ReservedSize(void) const
uint16_t
الحصول على عدد وحدات البايت ضمن المخزن المؤقت الحالي بين بداية المخزن المؤقت وموضع بدء البيانات الحالي
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
يتم تعيين طول البيانات بالبايت في المخزن المؤقت، مع ضبط الطول الإجمالي وفقًا لذلك.
SetStart(uint8_t *aNewStart)
void
قم بتعيين بيانات البدء في المخزن المؤقت، مع تعديل الطول وإجمالي الطول وفقًا لذلك.
Start(void) const
uint8_t *
الحصول على مؤشر لبدء البيانات في المخزن المؤقت
TotalLength(void) const
uint16_t
الحصول على إجمالي طول بيانات الحزمة في سلسلة المخزن المؤقت

الدوال الثابتة العامة
Free(PacketBuffer *aPacket)
void
حرر جميع المخازن المؤقتة للحزم في سلسلة.
FreeHead(PacketBuffer *aPacket)
حرّر أول مورد احتياطي في سلسلة، مع إظهار مؤشر الماوس للمورد الاحتياطي المتبقي.
New(void)
لتخصيص قيمة PacketBuffer واحدة من الحد الأقصى التلقائي للحجم (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) بالحجم التلقائي المحجوز (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) في الحمولة.
New(uint16_t aReservedSize)
يؤدي هذا الخيار إلى تخصيص قيمة PacketBuffer واحدة بالحد الأقصى للحجم الإجمالي مع حجم حجز رأسي محدَّد.
NewWithAvailableSize(size_t aAvailableSize)
لتخصيص PacketBuffer بالحجم التلقائي المحجوز (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) في حمولة العناوين، ومساحة aAllocSize بايت على الأقل للبيانات الإضافية بعد المؤشر الأولي.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
يتم تخصيص كائن PacketBuffer مع الاحتفاظ بمساحة aReservedSize بايت على الأقل في حمولة العناوين، ومساحة لا تقل عن aAllocSize بايت للبيانات الإضافية بعد مؤشر المؤشر الأولي.
RightSize(PacketBuffer *aPacket)
انسخ المخزن المؤقت المحدد إلى مخزن مؤقت بحجم مناسب إن أمكن.

وظائف عامة

AddRef

void AddRef(
  void
)

يجب زيادة عدد المراجع للمخزن المؤقت الحالي.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

أضف المخزن المؤقت للحزمة المحدد إلى نهاية سلسلة المخزن المؤقت، مع ضبط إجمالي طول كل مورد احتياطي في السلسلة وفقًا لذلك.

التفاصيل
المعلمات
[in] aPacket
- المخزن المؤقت للحزم المراد إضافته إلى نهاية السلسلة الحالية.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

محاذاة حمولة بيانات المخزن المؤقت على حدود البايت المحددة

نقل الحمولة في المخزن المؤقت إلى الأمام إذا لزم الأمر.

التفاصيل
المعلمات
[in] aAlignBytes
- يحدد عدد محاذاة وحدات البايت لمؤشر بدء الحمولة.
المرتجعات
true إذا تمت المحاذاة بنجاح، وfalse إذا لم تكن هناك مساحة كافية في المخزن المؤقت.

AllocSize

size_t AllocSize(
  void
) const

عرض حجم التخصيص بما في ذلك مساحات البيانات المحجوزة والحمولة، ولكن بدون تضمين المساحة المخصصة لبنية PacketBuffer

التفاصيل
المرتجعات
حجم التخصيص

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

احصل على عدد وحدات بايت البيانات التي يمكن إضافتها إلى المخزن المؤقت الحالي استنادًا إلى موضع البدء الحالي وطول البيانات.

التفاصيل
المرتجعات
طول البيانات بالبايت والتي تتناسب مع المخزن المؤقت الحالي وفقًا لموضع البدء الحالي وطول البيانات.

CompactHead

void CompactHead(
  void
)

نقل البيانات من المخازن المؤقتة اللاحقة في السلسلة إلى المخزن المؤقت الحالي حتى تمتلئ.

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

استهلاك

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

تستهلك البيانات في سلسلة من الموارد الاحتياطية.

استهلاك البيانات في سلسلة من الموارد الاحتياطية بدءًا من المورد الاحتياطي الحالي والانتقال عبر الموارد الاحتياطية المتبقية في السلسلة يتم تحرير كل مخزن احتياطي يتم استهلاكه بالكامل، وتعرض الدالة المخزن المؤقت الأول (إن وجد) الذي يحتوي على البيانات المتبقية. يجب أن يكون المورد الاحتياطي الحالي رأس سلسلة المورد الاحتياطي.

التفاصيل
المعلمات
[in] aConsumeLength
- عدد وحدات البايت المراد استهلاكها من السلسلة الحالية.
المرتجعات
المورد الاحتياطي الأول من السلسلة الحالية التي تحتوي على أي بيانات متبقية. إذا لم تتبق أي بيانات، فسيتم عرض NULL.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

قم بضبط المخزن المؤقت الحالي للإشارة إلى كمية البيانات المستهلكة.

تقدّم موضع بدء البيانات في المخزن المؤقت الحالي بمقدار الكمية المحددة، بالبايت، وصولاً إلى طول البيانات في المخزن المؤقت. قلِّل طول الفيديو وإجمالي الطول حسب الكمية المستهلكة.

التفاصيل
المعلمات
[in] aConsumeLen
- عدد وحدات البايت المراد استهلاكها من المخزن المؤقت الحالي.

DataLength

uint16_t DataLength(
  void
) const

الحصول على طول البيانات بالبايت في المخزن المؤقت للحزم

التفاصيل
المرتجعات
الطول بالبايت (طول الحمولة الحالي).

DetachTail

PacketBuffer * DetachTail(
  void
)

فصل المورد الاحتياطي الحالي من سلسلته وإعادة مؤشر إلى الموارد الاحتياطية المتبقية.

يجب أن يكون المورد الاحتياطي الحالي رأس السلسلة.

التفاصيل
المرتجعات
ذيل السلسلة الاحتياطية الحالية أو فارغ إذا كان المورد الاحتياطي الحالي هو المورد الاحتياطي الوحيد في السلسلة.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

تأكد من أن المورد الاحتياطي يحتوي على الأقل على القدر المحدد من المساحة المحجوزة.

تأكد من أن المورد الاحتياطي يحتوي على الأقل على مقدار محدد من المساحة المحجوزة لنقل البيانات في المخزن المؤقت للأمام لتوفير مساحة إذا لزم الأمر.

التفاصيل
المعلمات
[in] aReservedSize
- عدد وحدات البايت المطلوبة للعناوين.
المرتجعات
true إذا كان الحجم المحجوز المطلوب متاحًا، وfalse إذا لم تكن هناك مساحة كافية في المخزن المؤقت.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

الحصول على الحد الأقصى، بالبايت، من البيانات التي تلائم المخزن المؤقت وفقًا لموضع البدء الحالي وحجم المخزن المؤقت.

التفاصيل
المرتجعات
عدد وحدات البايت التي تتناسب مع المخزن المؤقت وفقًا لموضع البدء الحالي.

التالي

PacketBuffer * Next(
  void
) const

الحصول على مؤشر إلى المورد الاحتياطي التالي في السلسلة

التفاصيل
المرتجعات
مؤشر إلى المورد الاحتياطي التالي في السلسلة. يتم عرض NULL عندما لا تكون هناك مخازن مؤقتة في السلسلة.

ReservedSize

uint16_t ReservedSize(
  void
) const

الحصول على عدد وحدات البايت ضمن المخزن المؤقت الحالي بين بداية المخزن المؤقت وموضع بدء البيانات الحالي

التفاصيل
المرتجعات
مقدار المسافة بالبايت بين بداية المخزن المؤقت وموضع بدء البيانات الحالي.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

يتم تعيين طول البيانات بالبايت في المخزن المؤقت، مع ضبط الطول الإجمالي وفقًا لذلك.

تحدد الدالة طول البيانات في المخزن المؤقت، بالبايت، مع ضبط إجمالي الطول بشكل مناسب. عندما لا يكون المخزن المؤقت رأس سلسلة المخزن المؤقت (حالة شائعة: يضيف المتصل البيانات إلى المخزن المؤقت الأخير في سلسلة PacketBuffer قبل استدعاء طبقات أعلى)، يجب تمرير aChainHead بشكل صحيح لضبط الأطوال الإجمالية لكل مخزن مؤقت قبل المخزن المؤقت الحالي بشكل صحيح.

التفاصيل
المعلمات
[in] aNewLen
- المدة الجديدة لهذا المخزن المؤقت بالبايت.
[in,out] aChainHead
- رأس سلسلة المورد الاحتياطي الذي ينتمي إليها المورد الاحتياطي الحالي. قد يكون "NULL" (فارغ) إذا كان المورد الاحتياطي الحالي هو رأس سلسلة المورد الاحتياطي.

SetStart

void SetStart(
  uint8_t *aNewStart
)

قم بتعيين بيانات البدء في المخزن المؤقت، مع تعديل الطول وإجمالي الطول وفقًا لذلك.

التفاصيل
المعلمات
[in] aNewStart
- مؤشر إلى المكان الذي من المفترض أن تبدأ فيه الحمولة الجديدة سيتم ضبط newStart داخليًا لتصبح ضمن حدود المخزن المؤقت الأول في سلسلة PacketBuffer.

بدء

uint8_t * Start(
  void
) const

الحصول على مؤشر لبدء البيانات في المخزن المؤقت

التفاصيل
المرتجعات
يشير إلى بداية البيانات.

TotalLength

uint16_t TotalLength(
  void
) const

الحصول على إجمالي طول بيانات الحزمة في سلسلة المخزن المؤقت

التفاصيل
المرتجعات
وإجمالي الطول بالثُمانيات.

الدوال الثابتة العامة

مجانًا

void Free(
  PacketBuffer *aPacket
)

حرر جميع المخازن المؤقتة للحزم في سلسلة.

تقليل عدد المراجع إلى كل الموارد الاحتياطية في السلسلة الحالية. إذا وصل عدد المراجع إلى 0، يتم تفريغ الموارد الاحتياطية المعنيّة أو إرجاعها إلى مجموعات التخصيص حسب الحاجة. كقاعدة، على المستخدمين التعامل مع هذه الطريقة باعتبارها مكافئة لدالة free() وعدم استخدام الوسيطة بعد الاستدعاء.

التفاصيل
المعلمات
[in] aPacket
- سيتم تحرير المخزن المؤقت للحزمة.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

حرّر أول مورد احتياطي في سلسلة، مع إظهار مؤشر الماوس للمورد الاحتياطي المتبقي.

تعمل * @note When the buffer chain is referenced by multiple callers,FreeHead()" على فصل الرأس، ولكن لن تُفرط في ضبط موضع المخزن المؤقت للرأس.

التفاصيل
المعلمات
[in] aPacket
- سلسلة المورد الاحتياطي.
المرتجعات
سلسلة المخزن المؤقت للحزم التي تتألف من ذيل المخزن المؤقت للإدخال (قد يكون NULL).

جديد

PacketBuffer * New(
  void
)

لتخصيص قيمة PacketBuffer واحدة من الحد الأقصى التلقائي للحجم (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) بالحجم التلقائي المحجوز (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) في الحمولة.

الحجم المحجوز (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) كبير بما يكفي للاحتفاظ بعناوين طبقة النقل وكذلك الرؤوس التي يتطلبها WeaveMessageLayer وWeaveExchangeLayer.

جديد

PacketBuffer * New(
  uint16_t aReservedSize
)

يؤدي هذا الخيار إلى تخصيص قيمة PacketBuffer واحدة بالحد الأقصى للحجم الإجمالي مع حجم حجز رأسي محدَّد.

المعلمة التي يتم تمريرها هي الحجم المحجوز قبل الحمولة لاستيعاب عناوين حزم البيانات من طبقات تسلسل استدعاء الدوال البرمجية المختلفة، وليس الحجم الإجمالي للمخزن المؤقت المطلوب تخصيصه. حجم المخزن المؤقت WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX وليس محددًا في المكالمة.

  • PacketBuffer::New(0) : عند طلب ذلك بهذه الطريقة، سيتم عرض المخزن المؤقت بدون حجز أي عنوان، وبالتالي سيكون بإمكان المتصل استخدام الحمولة بالكامل. يفيد هذا النمط بشكل خاص في الطبقات السفلية من حزم الشبكات، في الحالات التي يعلم فيها المستخدم أنّه سيتم نسخ الحمولة إلى الرسالة النهائية مع احتياطيات العناوين المناسبة أو عند إنشاء PacketBuffer التي يتم إلحاقها بسلسلة من PacketBuffer عبر PacketBuffer::AddToEnd(). المعلمات
    [in] aReservedSize
    مقدار مساحة العنوان المراد حجزها.
    المرتجعات
    عند النجاح، يمكنك الإشارة إلى PacketBuffer، عند التعذُّر NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

لتخصيص PacketBuffer بالحجم التلقائي المحجوز (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) في حمولة العناوين، ومساحة aAllocSize بايت على الأقل للبيانات الإضافية بعد المؤشر الأولي.

يكون هذا الاستخدام أكثر ملاءمةً عند تخصيص PacketBuffer لرسالة من طبقة التطبيق.

التفاصيل
المعلمات
[in] aAvailableSize
عدد الثُمانيات المُراد تخصيصها بعد المؤشر.
المرتجعات
عند النجاح، يشير المؤشر إلى PacketBuffer في الوحدة المخصّصة. عند التعذُّر، NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

يتم تخصيص كائن PacketBuffer مع الاحتفاظ بمساحة aReservedSize بايت على الأقل في حمولة العناوين، ومساحة لا تقل عن aAllocSize بايت للبيانات الإضافية بعد مؤشر المؤشر الأولي.

التفاصيل
المعلمات
[in] aReservedSize
عدد الثُمانيات المطلوب حجزها خلف المؤشر.
[in] aAvailableSize
عدد الثُمانيات المُراد تخصيصها بعد المؤشر.
المرتجعات
عند النجاح، يشير المؤشر إلى PacketBuffer في الوحدة المخصّصة. عند التعذُّر، NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

انسخ المخزن المؤقت المحدد إلى مخزن مؤقت بحجم مناسب إن أمكن.

لا يمكن استخدام هذه الوظيفة للمقابس.

التفاصيل
المعلمات
[in] aPacket
- السلسلة الاحتياطية أو السلسلة الاحتياطية.
المرتجعات
المخزن المؤقت الجديد للحزم أو المخزن المؤقت الأصلي