nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

La clase de búfer de paquetes es la estructura principal utilizada para manipular paquetes de datos serializados en octeto, generalmente en el contexto de una red de comunicación de datos, como Bluetooth o el protocolo de Internet.

Resumen

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

La clase PacketBuffer, al igual que muchas estructuras similares que se usan en las pilas de red en capas, proporciona 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 por referencia, y el modo de uso predominante en Weave es "activar y olvidar". Como el paquete (y su objeto PacketBuffer subyacente) se despacha a través de varias capas de protocolo, la llamada ascendente o descendente exitosa entre capas implica la transferencia de propiedad, y el destinatario es responsable de liberar el búfer. Si falla una llamada entre capas, la responsabilidad de liberar el búfer es responsabilidad del emisor.

Los objetos nuevos de la clase PacketBuffer se inicializan al comienzo de una asignación de memoria obtenida del entorno subyacente, p.ej., desde grupos de destino del pbuf de LwIP, desde el montón de la biblioteca C estándar, desde un grupo de búfer 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 pueden estar encadenados 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 es compatible. Estos son algunos ejemplos de clases escritas con compatibilidad con el encadenamiento: 

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

Herencia

Se hereda de: pbuf

Funciones públicas
AddRef(void)
void
Aumenta el recuento de referencias del búfer actual.
AddToEnd(PacketBuffer *aPacket)
void
Agrega el búfer de paquetes determinado al final de la cadena de 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 con 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 sin el espacio asignado para la estructura PacketBuffer.
AvailableDataLength(void) const
uint16_t
Obtiene la cantidad de bytes de datos que se pueden agregar al búfer actual según la posición inicial y la longitud de los datos actuales.
CompactHead(void)
void
Mueve los datos de los búferes posteriores de la cadena al búfer actual hasta que esté completo.
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
Obtiene la longitud, en bytes, de los datos en el búfer de paquetes.
DetachTail(void)
Desconecta el búfer actual de su cadena y muestra un puntero a 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 cabe en el búfer según la posición inicial y el tamaño del búfer actuales.
Next(void) const
Se obtiene 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 su inicio y la posición de inicio de los datos actuales.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Configura la longitud, en bytes, de los datos en 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 *
Se obtiene un puntero para el inicio de los datos en búfer.
TotalLength(void) const
uint16_t
Obtiene la longitud total de los datos de un paquete 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 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 el tamaño reservado predeterminado (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) en la carga útil para los encabezados y al menos aAllocSize bytes de espacio para datos adicionales después del puntero inicial del cursor.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Asigna un objeto PacketBuffer con al menos aReservedSize bytes reservados en la carga útil para los 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 en un búfer del tamaño correcto, si corresponde.

Funciones públicas

AddRef

void AddRef(
  void
)

Aumenta el recuento de referencias del búfer actual.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Agrega el búfer de paquetes determinado al final de la cadena de 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 paquetes que se agregará al final de la cadena actual.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

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

Mover la carga útil en el búfer hacia adelante si es necesario

Detalles
Parámetros
[in] aAlignBytes
especifica la alineación de bytes para el puntero de inicio de la carga útil.
Resultado que se muestra
true si la alineación se realiza correctamente, false si no hay suficiente espacio en el búfer.

AllocSize

size_t AllocSize(
  void
) const

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

Detalles
Resultado que se muestra
tamaño de la asignación

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Obtiene la cantidad de bytes de datos que se pueden agregar al búfer actual según la posición inicial y la longitud de los datos actuales.

Detalles
Resultado que se muestra
la longitud, en bytes, de los datos que se adaptarán al búfer actual según la posición inicial y la longitud de los datos actuales.

CompactHead

void CompactHead(
  void
)

Mueve los datos de los búferes posteriores de la cadena al búfer actual hasta que esté completo.

Solo se compacta el búfer actual: los datos dentro del búfer actual se mueven al frente del búfer, lo que elimina el espacio reservado. El espacio disponible restante se llena con datos transferidos de los búferes posteriores de la cadena, hasta que el búfer actual esté completo. Si un búfer posterior de la cadena se traslada al búfer actual en su totalidad, se quita de la cadena y se libera. El método no toma 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 comenzando con el búfer actual y pasando por 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 hubiera) que contiene los datos restantes. El búfer actual debe ser el encabezado de la cadena de búferes.

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

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

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

Avanza la posición de inicio de los datos en el búfer actual según la cantidad especificada, en bytes, hasta la longitud de los datos en el búfer. Disminuye la duración y la duración total según la cantidad consumida.

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

DataLength

uint16_t DataLength(
  void
) const

Obtiene la longitud, en bytes, de los datos en el búfer de paquetes.

Detalles
Resultado que se muestra
en bytes (longitud actual de la carga útil).

DetachTail

PacketBuffer * DetachTail(
  void
)

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

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

Detalles
Resultado que se muestra
la cola de la cadena de búfer actual o NULL si el búfer actual es el único de la cadena.

EnsureReservedSize

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, moviendo los datos en el búfer hacia adelante para liberar espacio si es necesario.

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

MaxDataLength

uint16_t MaxDataLength(
  void
) const

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

Detalles
Resultado que se muestra
la cantidad de bytes que caben en el búfer según la posición inicial actual.

Siguiente

PacketBuffer * Next(
  void
) const

Se obtiene el puntero al siguiente búfer de la cadena.

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

ReservedSize

uint16_t ReservedSize(
  void
) const

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

Detalles
Resultado que se muestra
la cantidad, en bytes, de espacio entre el inicio del búfer y la posición de inicio de los datos actuales.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

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

La función establece la longitud, en bytes, de los datos en el búfer y ajusta la longitud total de forma adecuada. Cuando el búfer no es el principal de la cadena de búfer (caso común: el llamador agrega datos al último búfer en la cadena PacketBuffer antes de llamar a capas superiores), se debe pasar aChainHead para ajustar correctamente las longitudes totales de cada búfer antes del búfer actual.

Detalles
Parámetros
[in] aNewLen
- Es la nueva longitud, en bytes, de este búfer.
[in,out] aChainHead
- es la cabeza de la cadena de búfer a la que pertenece el búfer actual. Puede ser NULL si el búfer actual es el encabezado de la cadena de búferes.

SetStart

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 que indique dónde debe comenzar la nueva carga útil. newStart se ajustará internamente para que se encuentre dentro de los límites del primer búfer en la cadena PacketBuffer.

Iniciar

uint8_t * Start(
  void
) const

Se obtiene un puntero para el inicio de los datos en búfer.

Detalles
Resultado que se muestra
y el puntero hacia el inicio de los datos.

TotalLength

uint16_t TotalLength(
  void
) const

Obtiene la longitud total de los datos de un paquete en la cadena del búfer.

Detalles
Resultado que se muestra
la longitud total, en octetos.

Funciones estáticas públicas

Gratis

void Free(
  PacketBuffer *aPacket
)

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

Disminuye el recuento de referencias a todos los búferes en la cadena actual. Si el recuento de referencias alcanza 0, los búferes respectivos se liberan o se devuelven a los grupos de asignación según corresponda. Como regla, 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
- 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() se separará, pero no anulará la asignación del búfer de manera forzosa.

Detalles
Parámetros
[in] aPacket
- cadena de búferes.
Resultado que se muestra
cadena de búfer de paquetes que consiste en la parte final del búfer de entrada (puede ser NULL).

Nuevo

PacketBuffer * New(
  void
)

Asigna un solo PacketBuffer de tamaño máximo predeterminado (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) con 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 como para contener los encabezados de la capa de transporte, así como los encabezados requeridos para WeaveMessageLayer y WeaveExchangeLayer.

Nuevo

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 adaptarse a los encabezados del paquete de diferentes capas de pila, no el tamaño total 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 llama de esta manera, el búfer se muestra sin ningún encabezado reservado, por lo que el llamador puede usar toda la carga útil. Este patrón es particularmente útil en las capas inferiores de las pilas de red, en los casos en que el usuario sabe que la carga útil se copiará en el mensaje final con las reservas de encabezado apropiadas o cuando se crea un PacketBuffer que se agrega a una cadena de PacketBuffer a través de PacketBuffer::AddToEnd(). Parámetros
    [in] aReservedSize
    cantidad de espacio de encabezado a reservar.
    Qué muestra
    Si la operación es exitosa, un puntero a PacketBuffer, si falla NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

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

Este uso es el más apropiado cuando se asigna un PacketBuffer para un mensaje de la capa de la aplicación.

Detalles
Parámetros
[in] aAvailableSize
Cantidad de octetos para asignar después del cursor.
Resultado que se muestra
Si se realiza de forma correcta, un puntero a PacketBuffer en el bloque asignado. En caso de error, NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Asigna un objeto PacketBuffer con al menos aReservedSize bytes reservados en la carga útil para los 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 que se reservarán detrás del cursor.
[in] aAvailableSize
Cantidad de octetos para asignar después del cursor.
Resultado que se muestra
Si se realiza de forma correcta, un puntero a PacketBuffer en el bloque asignado. En caso de error, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Copia el búfer determinado en un búfer del tamaño correcto, si corresponde.

Esta función es no-op para sockets.

Detalles
Parámetros
[in] aPacket
- búfer o cadena de búfer.
Resultado que se muestra
nuevo búfer de paquetes o el búfer original