nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

סיווג מאגר נתונים זמני הוא המבנה הבסיסי שמשמש למניפולציה של חבילות נתונים שעברו סריאליזציה אוקטט, לרוב בהקשר של רשת תקשורת נתונים, כמו Bluetooth או פרוטוקול האינטרנט.

סיכום

בסביבות מבוססות LwIP, המחלקה הזו מבוססת על מבנה ה-pbuf המוגדר בספרייה הזו. בהיעדר LwIP, חברת Weave מספקת הטמעה שמבוססת על Maloc או הטמעה מבוססת-מאגר שקרובה מאוד לאתגרי הזיכרון של מכשירים מוטמעים עמוקים.

המחלקה PacketBuffer, בדומה למבנים דומים רבים שמשמשים בערימות רשת בשכבות, מספקים מנגנון לשמירת מקום לכותרות פרוטוקול בכל שכבה של סטאק תקשורת שניתן להגדרה. פרטים נוספים זמינים במאמר PacketBuffer::New() ובמסמכי התיעוד של LwIP.

אובייקטים מסוג PacketBuffer נספרים כקובצי עזר, ומצב השימוש הנפוץ ביותר ב-Weave הוא 'fire-and-שכח'. מאחר שהחבילה (ואובייקט PacketBuffer הבסיסי שלה) נשלחת דרך שכבות פרוטוקול שונות, הקריאה החוזרת (upcall) או ה-downcall המוצלחת בין שכבות מרמזות על העברת בעלות, והמקבל אחראי לשחרר את מאגר הנתונים הזמני. במקרה של כישלון בשיחה בין שכבות, האחריות לשחרור מאגר הנתונים הזמני תחול על המתקשר.

אובייקטים חדשים במחלקה PacketBuffer מאותחלים בתחילת הקצאת הזיכרון שמתקבלת מהסביבה הבסיסית, לדוגמה. ממאגרי יעד Pbuf של LwIP, מתוך הערימה הרגילה של ספריית C, ממאגר מאגר נתונים זמני פנימי. במקרה הפשוט, הגודל של מאגר הנתונים הזמני הוא WEAVE_SYSTEM_PACKETBUFFER_SIZE. יש לך מלחין שמאפשר להשתמש במאגרי נתונים בגדלים אחרים.

אובייקטים מסוג PacketBuffer עשויים להיות משורשרים כדי להכיל מטענים ייעודיים (payloads) גדולים יותר. עם זאת, שרשור לא יכול להיות שקוף, והמשתמשים בכיתה חייבים להחליט במפורש לתמוך ביצירת שרשורים. ריכזנו כאן דוגמאות לכיתות שנכתבו עם תמיכה ברצף: 

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

ירושה

עובר בירושה מ: pbuf

פונקציות ציבוריות
AddRef(void)
void
מגדילים את מספר ההפניות של מאגר הנתונים הזמני.
AddToEnd(PacketBuffer *aPacket)
void
מוסיפים את מאגר החבילות הנתון לסוף השרשרת של מאגר הנתונים הזמני, ומשנים את האורך הכולל של כל מאגר נתונים בשרשרת בהתאם.
AlignPayload(uint16_t aAlignBytes)
bool
צריך להתאים את המטען הייעודי (payload) של מאגר הנתונים הזמני בגבולות הבייטים שצוינו.
AllocSize(void) const
size_t
החזרת גודל ההקצאה, כולל מרחבי הנתונים השמורים והמטען הייעודי (payload), אבל לא כולל השטח שהוקצה למבנה 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) במטען הייעודי (payload).
New(uint16_t aReservedSize)
מחזירה PacketBuffer אחד בגודל כולל מקסימלי עם גודל שמור ספציפי של הכותרת.
NewWithAvailableSize(size_t aAvailableSize)
החלת PacketBuffer עם גודל שמור כברירת מחדל (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) במטען הייעודי (payload) לכותרות, ושטח של לפחות aAllocSize בייטים לנתונים נוספים לאחר הסמן הראשוני.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
כוללת באובייקט PacketBuffer לפחות aReservedSize בייטים שמורים במטען הייעודי (Payload) לכותרות, ולפחות aAllocSize בייטים של נתונים נוספים אחרי הסמן הראשוני.
RightSize(PacketBuffer *aPacket)
מעתיקים את מאגר הנתונים הזמני, אם רלוונטי, למאגר הנתונים הזמני.

פונקציות ציבוריות

AddRef

void AddRef(
  void
)

מגדילים את מספר ההפניות של מאגר הנתונים הזמני.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

מוסיפים את מאגר החבילות הנתון לסוף השרשרת של מאגר הנתונים הזמני, ומשנים את האורך הכולל של כל מאגר נתונים בשרשרת בהתאם.

פרטים
פרמטרים
[in] aPacket
- מאגר המנות שיתווסף בסוף השרשרת הנוכחית.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

צריך ליישר את המטען הייעודי (payload) של מאגר הנתונים הזמני בגבולות הבייטים שצוינו.

מעבירים את המטען הייעודי (payload) שבמאגר הנתונים הזמני, במקרה הצורך.

פרטים
פרמטרים
[in] aAlignBytes
- מציין את מספר היישור בבייטים של נקודת ההתחלה של המטען הייעודי (payload).
החזרות
true אם ההתאמה בוצעה בהצלחה, false אם אין מספיק מקום במאגר הנתונים הזמני.

AllocSize

size_t AllocSize(
  void
) const

החזרת גודל ההקצאה, כולל מרחבי הנתונים השמורים והמטען הייעודי (payload), אבל לא כולל השטח שהוקצה למבנה 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

קבלת אורך בבייטים של נתונים במאגר הנתונים הזמני.

פרטים
החזרות
length, בבייטים (אורך המטען הייעודי (payload) הנוכחי).

DetachTail

PacketBuffer * DetachTail(
  void
)

מנתקים את מאגר הנתונים הזמני מהשרשרת ומחזירים מצביע אל מאגרי הנתונים הזמניים הנותרים.

מאגר הנתונים הזמני חייב להיות הראשי בשרשרת.

פרטים
החזרות
ערך הזנב של שרשרת מאגר הנתונים הזמני או NULL, אם מאגר הנתונים הזמני הוא היחיד בשרשרת.

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
- מצביע למקום שבו צריך להתחיל המטען הייעודי (payload) החדש. ההתאמה של 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) במטען הייעודי (payload).

הגודל השמור (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) גדול מספיק כדי להחזיק כותרות של שכבות תעבורה וגם כותרות הנדרשות על ידי WeaveMessageLayer ו-WeaveExchangeLayer.

חדש

PacketBuffer * New(
  uint16_t aReservedSize
)

מחזירה PacketBuffer אחד בגודל כולל מקסימלי עם גודל שמור ספציפי של הכותרת.

הפרמטר שמועבר הוא הגודל שנשמר לפני המטען הייעודי (payload) כדי להכיל כותרות חבילות משכבות סטאק שונות, לא את הגודל הכולל של מאגר הנתונים הזמני שצריך להקצות. הגודל של מאגר הנתונים הזמני WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX ולא צוין בשיחה.

  • PacketBuffer::New(0) : כשמפעילים את הפונקציה הזו, מאגר הנתונים הזמני יוחזר בלי לשמור כותרת. כתוצאה מכך, המתקשר יכול להשתמש במטען הייעודי (Payload) כולו. הדפוס הזה שימושי במיוחד בשכבות הנמוכות של ערימות הרשת, במקרים שבהם המשתמש יודע שהמטען הייעודי (Payload) יועתק להודעה הסופית עם שמורות כותרות מתאימות, או כשיוצרים PacketBuffer שמצורף לשרשרת של PacketBuffer דרך PacketBuffer::AddToEnd(). פרמטרים
    [in] aReservedSize
    כמות השטח בכותרת שצריך לשמור.
    החזרות
    בהצלחה, מצביע אל PacketBuffer, בכשל NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

החלת PacketBuffer עם גודל שמור כברירת מחדל (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) במטען הייעודי (payload) לכותרות, ושטח אחסון של aAllocSize בייטים לפחות לנתונים נוספים לאחר הסמן הראשוני.

השימוש הזה הוא המתאים ביותר כשמקצים PacketBuffer להודעה בשכבת האפליקציה.

פרטים
פרמטרים
[in] aAvailableSize
מספר האוקטטים להקצאה אחרי הסמן.
החזרות
בסיום הפעולה, מצביע אל PacketBuffer בבלוק שהוקצה. במקרה של כישלון, NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

כוללת באובייקט PacketBuffer לפחות aReservedSize בייטים שמורים במטען הייעודי (Payload) לכותרות, ולפחות aAllocSize בייטים של נתונים נוספים אחרי הסמן הראשוני.

פרטים
פרמטרים
[in] aReservedSize
מספר אוקטטים לשמירה מאחורי הסמן.
[in] aAvailableSize
מספר האוקטטים להקצאה אחרי הסמן.
החזרות
בסיום הפעולה, מצביע אל PacketBuffer בבלוק שהוקצה. במקרה של כישלון, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

מעתיקים את מאגר הנתונים הזמני, אם רלוונטי, למאגר הנתונים הזמני.

הפונקציה הזו לא תקפה לשקעים.

פרטים
פרמטרים
[in] aPacket
- שרשרת מאגר נתונים או מאגר נתונים זמני.
החזרות
מאגר נתונים זמני חדש או מאגר נתונים זמני מקורי