nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

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

ملخّص

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

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

يتم احتساب كائنات PacketBuffer كمرجع، ووضع الاستخدام السائد في Weave هو "الإطلاق والحذف". بما أن الحزمة (وكائن 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
- رأس السلسلة الاحتياطية التي تنتمي إليها المورد الاحتياطي الحالي. قد تكون قيمة فارغة إذا كان المخزن المؤقت الحالي هو رأس سلسلة المورد الاحتياطي.

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)

New

PacketBuffer * New(
  void
)

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

الحجم المحجوز (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) كبير بما يكفي للاحتفاظ بعناوين طبقة النقل بالإضافة إلى العناوين المطلوبة من خلال WeaveMessageLayer وWeaveExchangeLayer.

New

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
- سلسلة المورد الاحتياطي.
المرتجعات
المخزن المؤقت الجديد للحزمة أو المخزن المؤقت الأصلي