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 |
|
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 |
|
||
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 |
|
||
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 |
|
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 |
|
||
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 |
|
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 |
|
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 |
|
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 |
|
||
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 dePacketBuffer::AddToEnd()
. Parámetros[in] aReservedSize
la cantidad de espacio de encabezado que se reservará.Si se ejecuta de forma correcta, un puntero a PacketBuffer, en caso de fallaNULL
.
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 |
|
||
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 |
|
||||
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 |
|
||
Qué muestra |
búfer de paquete nuevo o el búfer original
|