nl::Weave::Sistema::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

La clase del búfer de paquetes es la estructura principal utilizada para manipular paquetes de datos serializados en octetos, por lo general, en el contexto de una red de comunicaciones de datos, como Bluetooth o el protocolo de Internet.

Resumen

En entornos basados en LwIP, esta clase se crea sobre la estructura pbuf definida en esa biblioteca. Ante la ausencia de LwIP, Weave proporciona una implementación basada en malloc o una implementación basada en grupos que se acerca de cerca a los desafíos de memoria de dispositivos profundamente incorporados.

La clase PacketBuffer, al igual que muchas estructuras similares que se usan en pilas de red en capas, proporcionan un mecanismo para reservar espacio para encabezados de protocolo en cada capa de una pila de comunicación configurable. Para obtener más información, consulta PacketBuffer::New() y la documentación de LwIP.

Los objetos PacketBuffer se cuentan como referencia, y el modo de uso predominante dentro de Weave es &fire-and-forget. Dado que el paquete (y su objeto PacketBuffer subyacente) se despacha a través de varias capas de protocolo, la llamada ascendente o descendente correcta entre capas implica la transferencia de la propiedad, y el destinatario es responsable de liberar el búfer. En caso de que la llamada se realice de varias capas, la responsabilidad de liberar el búfer recae en el emisor.

Los objetos nuevos de la clase PacketBuffer se inicializan al comienzo de una asignación de memoria obtenida del entorno subyacente, p.ej., de grupos de destino pbuf de LwIP, del montón de la biblioteca C estándar, de un grupo de búferes interno. En el caso simple, el tamaño del búfer de datos es WEAVE_System_PACKETBUFFER_SIZE. Se proporciona un compositor que permite el uso de búferes de datos de otros tamaños.

Los objetos PacketBuffer se pueden encadenar para adaptarse a cargas útiles más grandes. Sin embargo, el encadenamiento no es transparente, y los usuarios de la clase deben decidir de forma explícita que lo admitan. Estos son algunos ejemplos de clases escritas con compatibilidad en cadena: 

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

Herencia

Hereda de: pbuf

Funciones públicas
AddRef(void)
void
Incrementa el recuento de referencia del búfer actual.
AddToEnd(PacketBuffer *aPacket)
void
Agrega el búfer de paquetes determinado al final de la cadena del búfer y ajusta la longitud total de cada búfer en la cadena según corresponda.
AlignPayload(uint16_t aAlignBytes)
bool
Alinea la carga útil del búfer en el límite de bytes especificado.
AllocSize(void) const
size_t
Muestra el tamaño de la asignación, incluidos los espacios de datos reservados y de carga útil, pero no incluye el espacio asignado para la estructura PacketBuffer.
AvailableDataLength(void) const
uint16_t
Obtén la cantidad de bytes de datos que se pueden agregar al búfer actual según la posición de inicio y la longitud de datos actuales.
CompactHead(void)
void
Mueve los datos de los búferes posteriores de la cadena al búfer actual hasta que se llene.
Consume(uint16_t aConsumeLength)
Consumir datos en una cadena de búferes
ConsumeHead(uint16_t aConsumeLength)
void
Ajusta el búfer actual para indicar la cantidad de datos consumidos.
DataLength(void) const
uint16_t
Obtén la longitud, en bytes, de los datos del búfer de paquetes.
DetachTail(void)
Desconecta el búfer actual de su cadena y muestra un puntero para los búferes restantes.
EnsureReservedSize(uint16_t aReservedSize)
bool
Asegúrate de que el búfer tenga al menos la cantidad especificada de espacio reservado.
MaxDataLength(void) const
uint16_t
Obtiene la cantidad máxima, en bytes, de datos que se ajustarán al búfer según la posición de inicio y el tamaño del búfer actuales.
Next(void) const
Obtener el puntero al siguiente búfer de la cadena.
ReservedSize(void) const
uint16_t
Obtén la cantidad de bytes dentro del búfer actual entre el inicio del búfer y la posición actual de inicio de los datos.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Configura la longitud en bytes de los datos del búfer y ajusta la longitud total según corresponda.
SetStart(uint8_t *aNewStart)
void
Configura los datos de inicio en búfer y ajusta la longitud y la longitud total según corresponda.
Start(void) const
uint8_t *
Obtén el puntero para el inicio de los datos en el búfer.
TotalLength(void) const
uint16_t
Obtén la longitud total de los datos de paquetes en la cadena del búfer.

Funciones estáticas públicas
Free(PacketBuffer *aPacket)
void
Libera todos los búferes de paquetes de una cadena.
FreeHead(PacketBuffer *aPacket)
Libera el primer búfer de una cadena y muestra un puntero a los búferes restantes.
New(void)
Asigna un solo PacketBuffer de tamaño máximo predeterminado (WEAVE_System_CONFIG_PACKETBUFFER_CAPACITY_MAX) con el tamaño reservado predeterminado (WEAVE_System_CONFIG_HEADER_RESERVE_SIZE) en la carga útil.
New(uint16_t aReservedSize)
Asigna un solo PacketBuffer de tamaño total máximo con un tamaño de reserva de encabezado específico.
NewWithAvailableSize(size_t aAvailableSize)
Asigna un PacketBuffer con tamaño reservado predeterminado (WEAVE_System_CONFIG_HEADER_RESERVE_SIZE) en la carga útil para encabezados y al menos aAllocSize bytes de espacio para datos adicionales después del puntero del cursor inicial.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Asigna un objeto PacketBuffer con al menos aReservedSize bytes reservados en la carga útil para encabezados y al menos aAllocSize bytes de espacio para datos adicionales después del puntero inicial del cursor.
RightSize(PacketBuffer *aPacket)
Copia el búfer determinado a un búfer de tamaño adecuado si corresponde.

Funciones públicas

Agregar referencia

void AddRef(
  void
)

Incrementa el recuento de referencia del búfer actual.

Agregar al final

void AddToEnd(
  PacketBuffer *aPacket
)

Agrega el búfer de paquetes determinado al final de la cadena del búfer y ajusta la longitud total de cada búfer en la cadena según corresponda.

Detalles
Parámetros
[in] aPacket
- el búfer de paquete que se agregará al final de la cadena actual.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Alinea la carga útil del búfer en el límite de bytes especificado.

Mover la carga útil al búfer si es necesario

Detalles
Parámetros
[in] aAlignBytes
- Especifica la cantidad de alineación de bytes para el puntero de inicio de carga útil.
Qué muestra
true si la alineación se realizó correctamente, false si no hay suficiente espacio en el búfer.

Tamaño de Alloc

size_t AllocSize(
  void
) const

Muestra el tamaño de la asignación, incluidos los espacios de datos reservados y de carga útil, pero no incluye el espacio asignado para la estructura PacketBuffer.

Detalles
Qué muestra
tamaño de la asignación

Longitud de datos disponibles

uint16_t AvailableDataLength(
  void
) const

Obtén la cantidad de bytes de datos que se pueden agregar al búfer actual según la posición de inicio y la longitud de datos actuales.

Detalles
Qué muestra
la longitud, en bytes, de los datos que se ajusten al búfer actual según la posición de inicio y la longitud de datos actuales.

CompactHead

void CompactHead(
  void
)

Mueve los datos de los búferes posteriores de la cadena al búfer actual hasta que se llene.

Solo se compacta el búfer actual: los datos dentro del búfer actual se mueven al frente del búfer, lo que elimina cualquier espacio reservado. El espacio disponible restante se llenará de datos transferidos de los búferes posteriores de la cadena, hasta que el búfer actual esté lleno. Si un búfer posterior de la cadena se traslada por completo al búfer actual, se elimina de la cadena y se libera. El método no recibe parámetros, no muestra resultados y no puede fallar.

Consumo

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Consumir datos en una cadena de búferes

Consumir datos en una cadena de búferes que comienza con el búfer actual y continúa con los búferes restantes de la cadena Cada búfer que se consume por completo se libera, y la función muestra el primer búfer (si lo hay) que contiene los datos restantes. El búfer actual debe ser el encabezado de la cadena del búfer.

Detalles
Parámetros
[in] aConsumeLength
- la cantidad de bytes que se consumirán en la cadena actual.
Qué muestra
el primer búfer de la cadena actual que contiene los datos restantes. Si no quedan datos, se muestra un valor NULL.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Ajusta el búfer actual para indicar la cantidad de datos consumidos.

Avanzar la posición de inicio de los datos al búfer actual según la cantidad especificada (en bytes) hasta la longitud de los datos del búfer Reduce la longitud y la longitud total en función de la cantidad consumida.

Detalles
Parámetros
[in] aConsumeLen
- la cantidad de bytes que se consumirán del búfer actual.

Longitud de los datos

uint16_t DataLength(
  void
) const

Obtén la longitud, en bytes, de los datos del búfer de paquetes.

Detalles
Qué muestra
longitud, en bytes (longitud actual de la carga útil).

DesconectarTail

PacketBuffer * DetachTail(
  void
)

Desconecta el búfer actual de su cadena y muestra un puntero para los búferes restantes.

El búfer actual debe ser el encabezado de la cadena.

Detalles
Qué muestra
La cola de la cadena del búfer actual o NULL si el búfer actual es el único búfer de la cadena

Tamaño de Reservad reservado

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Asegúrate de que el búfer tenga al menos la cantidad especificada de espacio reservado.

Asegúrate de que el búfer tenga, al menos, la cantidad especificada de espacio reservado que mueve los datos del búfer a fin de que haya espacio para ser necesario.

Detalles
Parámetros
[in] aReservedSize
- la cantidad de bytes deseados para los encabezados.
Qué muestra
true si el tamaño reservado solicitado está disponible, false si no hay suficiente espacio en el búfer.

Longitud máxima de los datos

uint16_t MaxDataLength(
  void
) const

Obtiene la cantidad máxima, en bytes, de datos que se ajustarán al búfer según la posición de inicio y el tamaño del búfer actuales.

Detalles
Qué muestra
cantidad de bytes que caben en el búfer según la posición de inicio actual

Siguiente

PacketBuffer * Next(
  void
) const

Obtener el puntero al siguiente búfer de la cadena.

Detalles
Qué muestra
un puntero al siguiente búfer de la cadena. Se muestra NULL cuando no hay búferes en la cadena.

Tamaño reservado

uint16_t ReservedSize(
  void
) const

Obtén la cantidad de bytes dentro del búfer actual entre el inicio del búfer y la posición actual de inicio de los datos.

Detalles
Qué muestra
cantidad de bytes, entre el inicio del búfer y la posición de inicio de datos actual, en bytes

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Configura la longitud en bytes de los datos del búfer y ajusta la longitud total según corresponda.

La función establece la longitud, en bytes, de los datos del búfer, ajustando la longitud total de forma adecuada. Cuando el búfer no es el encabezado de la cadena del búfer (en el caso común, el emisor agrega datos al último búfer de la cadena PacketBuffer antes de llamar a las capas superiores), debe pasarse el aChainHead para ajustar correctamente la longitud total de cada búfer antes del búfer actual.

Detalles
Parámetros
[in] aNewLen
- Nueva extensión, en bytes, de este búfer.
[in,out] aChainHead
- el encabezado de la cadena de búfer a la que pertenece el búfer actual Puede ser NULO si el búfer actual es el encabezado de la cadena del búfer.

Comenzar

void SetStart(
  uint8_t *aNewStart
)

Configura los datos de inicio en búfer y ajusta la longitud y la longitud total según corresponda.

Detalles
Parámetros
[in] aNewStart
- Un puntero al punto de inicio de la nueva carga útil. Se ajustará newStart de forma interna a fin de que quede dentro de los límites del primer búfer de la cadena PacketBuffer.

Iniciar

uint8_t * Start(
  void
) const

Obtén el puntero para el inicio de los datos en el búfer.

Detalles
Qué muestra
puntero al inicio de los datos.

Largo total

uint16_t TotalLength(
  void
) const

Obtén la longitud total de los datos de paquetes en la cadena del búfer.

Detalles
Qué muestra
longitud total, en octetos.

Funciones estáticas públicas

Gratis

void Free(
  PacketBuffer *aPacket
)

Libera todos los búferes de paquetes de una cadena.

Disminuir el recuento de referencia a todos los búferes de la cadena actual Si el recuento de referencias alcanza 0, los búferes correspondientes se liberan o se devuelven a los grupos de asignación según corresponda. Como regla general, los usuarios deben tratar este método como un equivalente de la función free() y no usar el argumento después de la llamada.

Detalles
Parámetros
[in] aPacket
- Es el búfer de paquetes que se liberará.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Libera el primer búfer de una cadena y muestra un puntero a los búferes restantes.

* @note When the buffer chain is referenced by multiple callers,FreeHead() separará la cabeza, pero no forzará la asignación del búfer de cabeza.

Detalles
Parámetros
[in] aPacket
- Cadena de búfer.
Qué muestra
Cadena de búfer de paquetes que consiste en la cola del búfer de entrada (puede ser NULL).

New

PacketBuffer * New(
  void
)

Asigna un solo PacketBuffer de tamaño máximo predeterminado (WEAVE_System_CONFIG_PACKETBUFFER_CAPACITY_MAX) con el tamaño reservado predeterminado (WEAVE_System_CONFIG_HEADER_RESERVE_SIZE) en la carga útil.

El tamaño reservado (WEAVE_System_CONFIG_HEADER_RESERVE_SIZE) es lo suficientemente grande para contener los encabezados de la capa de transporte, así como los encabezados requeridos por WeaveMessageLayer y WeaveExchangeLayer.

New

PacketBuffer * New(
  uint16_t aReservedSize
)

Asigna un solo PacketBuffer de tamaño total máximo con un tamaño de reserva de encabezado específico.

El parámetro que se pasa es el tamaño reservado antes de la carga útil para incluir encabezados de paquetes de diferentes capas de pila, no el tamaño general del búfer que se asignará. El tamaño del búfer WEAVE_System_CONFIG_PACKETBUFFER_CAPACITY_MAX y no especificado en la llamada.

  • PacketBuffer::New(0): Cuando se lo llama de esta manera, se muestra el búfer sin ningún encabezado reservado, por lo que el emisor puede usar toda la carga útil. Este patrón es particularmente útil en las capas inferiores de las pilas de redes, en los casos en que el usuario sabe que la carga útil se copia en el mensaje final con las reservas de encabezado apropiadas o en la creación de PacketBuffer que se agrega a una cadena de PacketBuffer a través de PacketBuffer::AddToEnd(). Parámetros
    [in] aReservedSize
    espacio disponible en el encabezado para reservar.
    Qué muestra
    Si se realiza correctamente, un puntero para PacketBuffer, en la falla NULL.

Nuevo con el tamaño disponible

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Asigna un PacketBuffer con tamaño reservado predeterminado (WEAVE_System_CONFIG_HEADER_RESERVE_SIZE) en la carga útil para encabezados y al menos aAllocSize bytes de espacio para datos adicionales después del puntero del cursor inicial.

Este uso es más adecuado cuando se asigna un PacketBuffer a un mensaje de la capa de la aplicación.

Detalles
Parámetros
[in] aAvailableSize
Cantidad de octetos que se asignarán después del cursor.
Qué muestra
Si la operación es exitosa, un puntero a PacketBuffer en el bloque asignado. En caso de error, NULL. *

Nuevo con el tamaño disponible

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Asigna un objeto PacketBuffer con al menos aReservedSize bytes reservados en la carga útil para encabezados y al menos aAllocSize bytes de espacio para datos adicionales después del puntero inicial del cursor.

Detalles
Parámetros
[in] aReservedSize
Cantidad de octetos para reservar detrás del cursor.
[in] aAvailableSize
Cantidad de octetos que se asignarán después del cursor.
Qué muestra
Si la operación es exitosa, un puntero a PacketBuffer en el bloque asignado. En caso de error, NULL.

Tamaño derecho

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Copia el búfer determinado a un búfer de tamaño adecuado si corresponde.

Esta función es no-op para sockets.

Detalles
Parámetros
[in] aPacket
- búfer o cadena de búfer.
Qué muestra
nuevo búfer de paquete o el búfer original