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