تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

nl::Weave::النظام::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

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

الملخّص

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

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

يتم احتساب كائنات PacketBuffer، ويكون وضع الاستخدام السائد في Weave هو "fire-and-forget". أثناء إرسال الحزمة (وعنصرها الأساسي 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_x_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)
نسخ المخزن المؤقت المحدد إلى المخزن المؤقت بالحجم الصحيح إن أمكن.

وظائف عامة

إضافة مرجع

void AddRef(
  void
)

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

إضافة إلى نهاية

void AddToEnd(
  PacketBuffer *aPacket
)

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

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

محاذاة Payload

bool AlignPayload(
  uint16_t aAlignBytes
)

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

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

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

تخصيص حجم

size_t AllocSize(
  void
) const

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

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

طول البيانات المتاحة

uint16_t AvailableDataLength(
  void
) const

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

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

مكثف مضغوط

void CompactHead(
  void
)

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

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

استهلاك

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

استهلاك البيانات في سلسلة من المخزن المؤقت.

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

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

استخدام الاستهلاك

void ConsumeHead(
  uint16_t aConsumeLength
)

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

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

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

طول البيانات

uint16_t DataLength(
  void
) const

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

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

فصل الهاتف

PacketBuffer * DetachTail(
  void
)

افصل المخزن المؤقت الحالي عن سلسلته وارجع المؤشر إلى المخزن المؤقت المتبقي.

يجب أن يكون المخزن المؤقت الحالي هو رأس السلسلة.

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

ضمان بحجم محجوز

bool EnsureReservedSize(
  uint16_t aReservedSize
)

تأكد من أن المخزن المؤقت يحتوي على المساحة المحددة على الأقل.

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

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

الحد الأقصى لطول البيانات

uint16_t MaxDataLength(
  void
) const

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

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

التالي

PacketBuffer * Next(
  void
) const

يمكنك الحصول على إشارة إلى المخزن المؤقت التالي في السلسلة.

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

الحجم المحجوزة

uint16_t ReservedSize(
  void
) const

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

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

طول البيانات

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

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

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

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

ضبط البدء

void SetStart(
  uint8_t *aNewStart
)

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

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

بدء

uint8_t * Start(
  void
) const

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

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

الطول الإجمالي

uint16_t TotalLength(
  void
) const

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

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

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

مجاني

void Free(
  PacketBuffer *aPacket
)

إخلاء جميع المخازن المؤقتة للحزم في إحدى السلاسل.

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

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

فري هيد

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_x_RESERVE_SIZE) في الحمولة.

الحجم المحجوز (WEAVE_SYSTEM_CONFIG_ADGROUPCOUNT_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.

جديد مع الحجم المتاح

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

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

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

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

جديد مع الحجم المتاح

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

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

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

الحجم الأيمن

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

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

هذه الدالة هي بيئة مستقلة للمقابس.

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