nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

La clase de búfer de paquetes es la estructura principal que se usa para manipular paquetes de datos serializados en octetos, por lo general, 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 en pool que se aproxima de manera aproximada a los desafíos de memoria de los dispositivos profundamente incorporados.

La clase PacketBuffer, al igual que muchas estructuras similares que se usan en 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 detalles, consulta PacketBuffer::New() y la documentación de LwIP.

Los objetos PacketBuffer se cuentan por referencia, y el modo de uso actual de Weave es "activar y olvidar". A medida que el paquete (y su objeto PacketBuffer subyacente) se envía a través de varias capas de protocolo, la llamada ascendente o descendente correcta entre las capas implica una transferencia de propiedad, y el destinatario es responsable de liberar el búfer. En caso de falla de una llamada entre 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 de pbuf de LwIP, del montón de biblioteca C estándar, desde 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 explícitamente admitir el encadenamiento. Estos son algunos ejemplos de clases escritas compatibles con el encadenamiento: 

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

Herencia

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úferes 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 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 de inicio y la longitud de datos actuales.
CompactHead(void)
void
Mover los datos de los búferes posteriores de la cadena al búfer actual hasta que estén llenos.
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)
Separa el búfer actual de su cadena y devuelve 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 caben en el búfer según la posición de inicio y el tamaño del búfer actuales.
Next(void) const
Obtiene el puntero al siguiente búfer de la cadena.
ReservedSize(void) const
uint16_t
Obtiene la cantidad de bytes dentro del búfer actual entre el inicio del búfer y la posición de inicio de los datos actual.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Configura la longitud (en bytes) de los datos en el búfer y ajusta la longitud total según corresponda.
SetStart(uint8_t *aNewStart)
void
Configura los datos de inicio en el búfer y ajusta la longitud y la longitud total según corresponda.
Start(void) const
uint8_t *
Obtiene un 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 de 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 devuelve 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 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 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 los encabezados y al menos aAllocSize bytes de espacio para datos adicionales después del puntero de cursor inicial.
RightSize(PacketBuffer *aPacket)
Copia el búfer determinado en uno de tamaño adecuado, 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úferes y ajusta la longitud total de cada búfer en la cadena según corresponda.

Detalles
Parámetros
[in] aPacket
- Es 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 en el búfer hacia delante si es necesario

Detalles
Parámetros
[in] aAlignBytes
- especifica la cantidad de bytes de alineación para el puntero de inicio de la carga útil.
Qué muestra
true si la alineación es correcta y 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
Qué 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 de inicio y la longitud de datos actuales.

Detalles
Qué muestra
es la longitud, en bytes, de los datos que caben en el búfer actual dada la posición de inicio y la longitud de datos actuales.

CompactHead

void CompactHead(
  void
)

Mover los datos de los búferes posteriores de la cadena al búfer actual hasta que estén llenos.

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 llena con datos que se mueven desde búferes posteriores en la cadena hasta que el búfer actual esté completo. Si un búfer posterior de la cadena se mueve por completo al búfer actual, 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 que comienza con el búfer actual y sigue a través de 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 de búferes.

Detalles
Parámetros
[in] aConsumeLength
- Es la cantidad de bytes que se consumirán de la cadena actual.
Qué muestra
el primer búfer de la cadena actual que contiene los datos restantes. Si no quedan datos, se muestra 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 la cantidad especificada, en bytes, hasta la longitud de los datos en el búfer. Disminuye la duración y la longitud 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
Qué muestra
en bytes (longitud de la carga útil actual).

DetachTail

PacketBuffer * DetachTail(
  void
)

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

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

Detalles
Qué muestra
la cola de la cadena de búferes 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 que mueva los datos en el búfer hacia delante para hacer espacio, si es necesario.

Detalles
Parámetros
[in] aReservedSize
- cantidad de bytes deseados para los encabezados.
Qué 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 caben en el búfer según la posición de inicio y el tamaño del búfer actuales.

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

Siguiente

PacketBuffer * Next(
  void
) const

Obtiene 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.

ReservedSize

uint16_t ReservedSize(
  void
) const

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

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

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

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

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

Detalles
Parámetros
[in] aNewLen
- nueva longitud, en bytes, de este búfer.
[in,out] aChainHead
Es el encabezado 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 el búfer y ajusta la longitud y la longitud total según corresponda.

Detalles
Parámetros
[in] aNewStart
- Un puntero hacia el lugar donde debería comenzar la nueva carga útil. El valor newStart se ajustará internamente para que se encuentre dentro de los límites del primer búfer de la cadena PacketBuffer.

Inicio

uint8_t * Start(
  void
) const

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

Detalles
Qué muestra
puntero al inicio de los datos.

TotalLength

uint16_t TotalLength(
  void
) const

Obtén la longitud total de los datos de paquetes en la cadena de 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 referencias a todos los búferes de la cadena actual Si el recuento de referencias llega a 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
- búfer de paquete que se liberará.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

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

* @note When the buffer chain is referenced by multiple callers,FreeHead()` separará el encabezado, pero no anulará la asignación forzada del búfer principal.

Detalles
Parámetros
[in] aPacket
- cadena de búfer.
Qué muestra
cadena de búfer de paquetes formada por la cola 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 que requieren 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 adaptar los encabezados de paquetes 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, se mostrará el búfer 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 redes, en los casos en que el usuario sepa que la carga útil se copiará en el mensaje final con las reservas de encabezado adecuadas o en la creación de PacketBuffer que se agregan a una cadena de PacketBuffer a través de PacketBuffer::AddToEnd(). Parámetros
    [in] aReservedSize
    la cantidad de espacio de encabezado que se reservará.
    Qué muestra
    Si se ejecuta de forma correcta, un puntero a PacketBuffer, en caso de falla NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Asigna un PacketBuffer con 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 del cursor inicial.

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 que se asignarán después del cursor.
Qué muestra
En caso de éxito, un puntero a PacketBuffer en el bloque asignado. Si falla, 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 de cursor inicial.

Detalles
Parámetros
[in] aReservedSize
Número de octetos que se deben reservar detrás del cursor
[in] aAvailableSize
Cantidad de octetos que se asignarán después del cursor.
Qué muestra
En caso de éxito, un puntero a PacketBuffer en el bloque asignado. Si falla, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Copia el búfer determinado en uno de tamaño adecuado, si corresponde.

Esta función es una no-op para los sockets.

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