nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

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

סיכום

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

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

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

אובייקטים חדשים של המחלקה PacketBuffer מאותחלים בתחילת ההקצאה של זיכרון שמתקבל מהסביבה הבסיסית, למשל ממאגרי יעד של LwIP pbuf, מ-heap של ספרייה רגילה של 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
יישר את המטען הזמני של מאגר הנתונים הזמני בגבול הבייטים שצוין.
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) במטען הייעודי (payload) של גודל שמור כברירת מחדל (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE).
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) קדימה במאגר הנתונים הזמני, אם יש צורך.

פרטים
פרמטרים
[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

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

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

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

פרטים
פרמטרים
[in] aPacket
- שרשרת מאגר נתונים זמני.
החזרות
שרשרת מאגר חבילות שמכילה את הזנב של מאגר הנתונים הזמני (יכול להיות NULL).

חדש

PacketBuffer * New(
  void
)

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

הגודל השמור (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
)

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

הפונקציה הזו לא מאפשרת ביצוע פעולות ב-sockets.

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