nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

패킷 버퍼 클래스는 일반적으로 블루투스 또는 인터넷 프로토콜과 같은 데이터 통신 네트워크의 컨텍스트에서 옥텟 직렬화된 데이터의 패킷을 조작하는 데 사용되는 핵심 구조입니다.

요약

LwIP 기반 환경에서 이 클래스는 라이브러리에 정의된 pbuf 구조를 기반으로 빌드됩니다. LwIP가 없을 경우 Weave는 malloc 기반 구현 또는 깊이 임베디드 디바이스의 메모리 문제에 근접한 풀 기반 구현을 제공합니다.

계층화된 네트워크 스택에 사용되는 여러 유사한 구조와 마찬가지로 PacketBuffer 클래스는 구성 가능한 통신 스택의 각 레이어에서 프로토콜 헤더를 위한 공간을 예약하는 메커니즘을 제공합니다. 자세한 내용은 PacketBuffer::New() 및 LwIP 문서를 참고하세요.

PacketBuffer 객체는 참조로 계산되며, Weave 내에서 일반적으로 사용되는 사용 모드는 'fire-and-forget'입니다. 패킷 (및 기본 PacketBuffer 객체)이 다양한 프로토콜 레이어를 통해 전달되므로 레이어 간의 성공적인 업콜 또는 다운콜은 소유권 이전을 의미하며 피호출자는 버퍼 해제를 담당합니다. 교차 레이어 호출이 실패하면 버퍼 해제 책임은 호출자에 있습니다.

PacketBuffer 클래스의 새로운 객체는 기본 환경에서 얻은 메모리 할당이 시작될 때 초기화됩니다.예를 들면 다음과 같습니다. LwIP pbuf 대상 풀, 표준 C 라이브러리 힙, 내부 버퍼 풀에서. 간단한 사례에서 데이터 버퍼의 크기는 WEAVE_SYSTEM_PACKETBUFFER_SIZE입니다. 다른 크기의 데이터 버퍼 사용을 허용하는 컴포저가 제공됩니다.

PacketBuffer 객체는 더 큰 페이로드를 수용하도록 체인으로 연결될 수 있음. 그러나 체이닝은 투명하지 않으며 클래스의 사용자는 체이닝을 지원하도록 명시적으로 결정해야 합니다. 체이닝 지원을 포함하여 작성된 클래스의 예는 다음과 같습니다.

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

상속

상속 출처: pbuf

공개 함수

AddRef(void)
void
현재 버퍼의 참조 수를 증가시킵니다.
AddToEnd(PacketBuffer *aPacket)
void
지정된 패킷 버퍼를 버퍼 체인 끝에 추가하고 이에 따라 체인에 있는 각 버퍼의 총 길이를 조정합니다.
AlignPayload(uint16_t aAlignBytes)
bool
지정된 바이트 경계에서 버퍼 페이로드를 정렬합니다.
AllocSize(void) const
size_t
예약된 데이터 공간과 페이로드 데이터 공간을 포함한 할당 크기를 반환하지만 PacketBuffer 구조에 할당된 공간은 포함하지 않습니다.
AvailableDataLength(void) const
uint16_t
현재 시작 위치와 데이터 길이를 고려하여 현재 버퍼에 추가할 수 있는 데이터의 바이트 수를 가져옵니다.
CompactHead(void)
void
가득 찰 때까지 체인의 후속 버퍼에서 현재 버퍼로 데이터를 이동합니다.
Consume(uint16_t aConsumeLength)
버퍼 체인의 데이터 사용
ConsumeHead(uint16_t aConsumeLength)
void
현재 버퍼를 조정하여 소비된 데이터 양을 표시합니다.
DataLength(void) const
uint16_t
패킷 버퍼에 있는 데이터의 길이(바이트)를 가져옵니다.
DetachTail(void)
체인에서 현재 버퍼를 분리하고 나머지 버퍼를 가리키는 포인터를 반환합니다.
EnsureReservedSize(uint16_t aReservedSize)
bool
버퍼에 최소한 지정된 양의 예약된 공간이 있어야 합니다.
MaxDataLength(void) const
uint16_t
현재 시작 위치와 버퍼 크기를 고려하여 버퍼에 적합한 데이터의 최대 양(바이트)을 가져옵니다.
Next(void) const
체인의 다음 버퍼에 대한 포인터를 가져옵니다.
ReservedSize(void) const
uint16_t
버퍼의 시작과 현재 데이터 시작 위치 사이의 현재 버퍼 내의 바이트 수를 가져옵니다.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
버퍼에서 데이터의 길이(바이트)를 설정하고 그에 따라 총 길이를 조정합니다.
SetStart(uint8_t *aNewStart)
void
버퍼에 시작 데이터를 설정하여 길이와 총 길이를 적절히 조정합니다.
Start(void) const
uint8_t *
버퍼의 데이터 시작 포인터를 가져옵니다.
TotalLength(void) const
uint16_t
버퍼 체인에 있는 패킷 데이터의 총 길이를 가져옵니다.

공개 정적 함수

Free(PacketBuffer *aPacket)
void
체인의 모든 패킷 버퍼를 해제합니다.
FreeHead(PacketBuffer *aPacket)
체인의 첫 번째 버퍼를 해제하고 나머지 버퍼를 가리키는 포인터를 반환합니다.
New(void)
페이로드에 기본 최대 크기 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX)의 단일 PacketBuffer를 예약된 기본 크기 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)와 함께 할당합니다.
New(uint16_t aReservedSize)
특정 헤더 예약 크기로 최대 총 크기의 단일 PacketBuffer를 할당합니다.
NewWithAvailableSize(size_t aAvailableSize)
헤더의 경우 페이로드에 기본 예약된 크기 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)로 PacketBuffer를 할당하고, 초기 커서 포인터 뒤에는 추가 데이터를 위한 최소 aAllocSize 바이트의 공간을 할당합니다.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
헤더의 경우 페이로드에 aReservedSize바이트 이상, 초기 커서 포인터 뒤에는 추가 데이터를 위한 aAllocSize바이트 이상의 공간이 있는 PacketBuffer 객체를 할당합니다.
RightSize(PacketBuffer *aPacket)
해당하는 경우 지정된 버퍼를 적절한 크기의 버퍼에 복사합니다.

공개 함수

AddRef

void AddRef(
  void
)

현재 버퍼의 참조 수를 증가시킵니다.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

지정된 패킷 버퍼를 버퍼 체인 끝에 추가하고 이에 따라 체인에 있는 각 버퍼의 총 길이를 조정합니다.

세부정보
매개변수
[in] aPacket
- 현재 체인의 끝에 추가될 패킷 버퍼.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

지정된 바이트 경계에서 버퍼 페이로드를 정렬합니다.

필요한 경우 버퍼의 페이로드를 앞으로 이동합니다.

세부정보
매개변수
[in] aAlignBytes
- 페이로드 시작 포인터의 바이트 정렬 수를 지정합니다.
반환
정렬에 성공하면 true, 버퍼에 공간이 충분하지 않으면 false입니다.

AllocSize

size_t AllocSize(
  void
) const 

예약된 데이터 공간과 페이로드 데이터 공간을 포함한 할당 크기를 반환하지만 PacketBuffer 구조에 할당된 공간은 포함하지 않습니다.

세부정보
반환
할당 크기

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const 

현재 시작 위치와 데이터 길이를 고려하여 현재 버퍼에 추가할 수 있는 데이터의 바이트 수를 가져옵니다.

세부정보
반환
현재 시작 위치와 데이터 길이를 고려하여 현재 버퍼에 적합한 데이터의 길이(바이트)입니다.

CompactHead

void CompactHead(
  void
)

가득 찰 때까지 체인의 후속 버퍼에서 현재 버퍼로 데이터를 이동합니다.

현재 버퍼만 압축됩니다. 현재 버퍼 내의 데이터가 버퍼의 앞으로 이동하므로 예약된 공간이 제거됩니다. 현재 버퍼가 가득 찰 때까지 남은 사용 가능한 공간은 체인의 후속 버퍼에서 이동한 데이터로 채워집니다. 체인의 후속 버퍼가 전체 현재 버퍼로 이동하면 체인에서 삭제되며 해제됩니다. 이 메서드는 파라미터를 사용하지 않고 결과를 반환하지 않으며 실패할 수 없습니다.

소비

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

버퍼 체인의 데이터 사용

현재 버퍼부터 시작하여 체인의 나머지 버퍼를 진행하면서 버퍼 체인에서 데이터를 소비합니다. 완전히 사용된 각 버퍼는 해제되고 함수는 나머지 데이터가 포함된 첫 번째 버퍼 (있는 경우)를 반환합니다. 현재 버퍼는 버퍼 체인의 헤드여야 합니다.

세부정보
매개변수
[in] aConsumeLength
- 현재 체인에서 소비할 바이트 수입니다.
반환
남은 데이터를 포함하는 현재 체인의 첫 번째 버퍼입니다. 남아 있는 데이터가 없으면 NULL이 반환됩니다.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

현재 버퍼를 조정하여 소비된 데이터 양을 표시합니다.

현재 버퍼의 데이터 시작 위치를 버퍼의 데이터 길이까지 지정된 양(바이트)만큼 이동합니다. 길이와 총 길이를 소비량만큼 줄입니다.

세부정보
매개변수
[in] aConsumeLen
- 현재 버퍼에서 소비할 바이트 수입니다.

DataLength

uint16_t DataLength(
  void
) const 

패킷 버퍼에 있는 데이터의 길이(바이트)를 가져옵니다.

세부정보
반환
바이트 단위의 길이 (현재 페이로드 길이)입니다.

DetachTail

PacketBuffer * DetachTail(
  void
)

체인에서 현재 버퍼를 분리하고 나머지 버퍼를 가리키는 포인터를 반환합니다.

현재 버퍼는 체인의 헤드여야 합니다.

세부정보
반환
현재 버퍼 체인의 꼬리 또는 현재 버퍼가 체인의 유일한 버퍼인 경우 NULL.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

버퍼에 최소한 지정된 양의 예약된 공간이 있어야 합니다.

필요한 경우 여유 공간을 확보하기 위해 버퍼에 버퍼의 데이터를 앞으로 이동하는 지정된 양의 예약된 공간이 버퍼에 있는지 확인합니다.

세부정보
매개변수
[in] aReservedSize
- 헤더에 필요한 바이트 수입니다.
반환
요청된 예약된 크기를 사용할 수 있는 경우 true, 버퍼에 공간이 충분하지 않으면 false

MaxDataLength

uint16_t MaxDataLength(
  void
) const 

현재 시작 위치와 버퍼 크기를 고려하여 버퍼에 적합한 데이터의 최대 양(바이트)을 가져옵니다.

세부정보
반환
현재 시작 위치를 고려하여 버퍼에 들어가는 바이트 수입니다.

다음

PacketBuffer * Next(
  void
) const 

체인의 다음 버퍼에 대한 포인터를 가져옵니다.

세부정보
반환
체인의 다음 버퍼를 가리키는 포인터입니다. 체인에 버퍼가 없으면 NULL가 반환됩니다.

ReservedSize

uint16_t ReservedSize(
  void
) const 

버퍼의 시작과 현재 데이터 시작 위치 사이의 현재 버퍼 내의 바이트 수를 가져옵니다.

세부정보
반환
버퍼의 시작과 현재 데이터 시작 위치 사이의 공간 크기(바이트)입니다.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

버퍼에서 데이터의 길이(바이트)를 설정하고 그에 따라 총 길이를 조정합니다.

이 함수는 버퍼에 있는 데이터의 길이를 바이트 단위로 설정하여 총 길이를 적절히 조정합니다. 버퍼가 버퍼 체인의 헤드가 아닌 경우 (일반적인 경우: 호출자가 상위 계층을 호출하기 전에 PacketBuffer 체인의 마지막 버퍼에 데이터를 추가함) aChainHead를 전달해야 현재 버퍼보다 앞서 각 버퍼의 총 길이를 적절하게 조정할 수 있습니다.

세부정보
매개변수
[in] aNewLen
- 이 버퍼의 새 길이(바이트)입니다.
[in,out] aChainHead
- 현재 버퍼가 속한 버퍼 체인의 헤드. 현재 버퍼가 버퍼 체인의 헤드인 경우 NULL일 수 있습니다.

SetStart

void SetStart(
  uint8_t *aNewStart
)

버퍼에 시작 데이터를 설정하여 길이와 총 길이를 적절히 조정합니다.

세부정보
매개변수
[in] aNewStart
- 새 페이로드가 시작될 위치를 가리키는 포인터입니다. newStart는 PacketBuffer 체인의 첫 번째 버퍼 경계 내에 있도록 내부적으로 조정됩니다.

시작

uint8_t * Start(
  void
) const 

버퍼의 데이터 시작 포인터를 가져옵니다.

세부정보
반환
데이터 시작을 가리키는 포인터입니다.

TotalLength

uint16_t TotalLength(
  void
) const 

버퍼 체인에 있는 패킷 데이터의 총 길이를 가져옵니다.

세부정보
반환
총 길이를 옥텟으로 나타냅니다.

공개 정적 함수

무료

void Free(
  PacketBuffer *aPacket
)

체인의 모든 패킷 버퍼를 해제합니다.

현재 체인의 모든 버퍼로의 참조 수를 줄입니다. 참조 수가 0에 도달하면 각 버퍼가 해제되거나 적절하게 할당 풀로 반환됩니다. 일반적으로 사용자는 이 메서드를 free() 함수와 동등한 것으로 취급해야 하며 호출 후에 인수를 사용하지 않아야 합니다.

세부정보
매개변수
[in] aPacket
- 해제할 패킷 버퍼입니다.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

체인의 첫 번째 버퍼를 해제하고 나머지 버퍼를 가리키는 포인터를 반환합니다.

* @note When the buffer chain is referenced by multiple callers,FreeHead()` 는 헤드를 분리하지만 강제로 헤드 버퍼를 할당 해제하지 않습니다.

세부정보
매개변수
[in] aPacket
- 버퍼 체인입니다.
반환
입력 버퍼의 꼬리로 구성된 패킷 버퍼 체인입니다 (NULL일 수 있음).

신규

PacketBuffer * New(
  void
)

페이로드에 기본 최대 크기 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX)의 단일 PacketBuffer를 예약된 기본 크기 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)와 함께 할당합니다.

예약된 크기 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)는 전송 계층 헤더와 WeaveMessageLayerWeaveExchangeLayer에 필요한 헤더를 보관할 만큼 충분히 큽니다.

신규

PacketBuffer * New(
  uint16_t aReservedSize
)

특정 헤더 예약 크기로 최대 총 크기의 단일 PacketBuffer를 할당합니다.

전달되는 매개변수는 할당할 버퍼의 전체 크기가 아니라 다른 스택 계층의 패킷 헤더를 수용하기 위해 페이로드 전에 예약된 크기입니다. 호출에 지정되지 않은 WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX 버퍼의 크기입니다.

  • PacketBuffer::New(0) : 이 방식으로 호출하면 예약된 헤더 없이 버퍼가 반환되므로 호출자가 전체 페이로드를 사용할 수 있습니다. 이 패턴은 페이로드가 적절한 헤더 예약을 사용하여 최종 메시지로 복사된다는 것을 사용자가 알고 있거나 PacketBuffer::AddToEnd()를 통해 PacketBuffer 체인에 추가되는 PacketBuffer를 만들 때 특히 유용한 네트워킹 스택의 하위 계층에서 유용합니다. 매개변수
    [in] aReservedSize
    충분한 헤더 공간이 필요합니다.
    반환
    성공 시 NULL 실패 시 PacketBuffer를 가리키는 포인터

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

헤더의 경우 페이로드에 기본 예약된 크기 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)로 PacketBuffer를 할당하고, 초기 커서 포인터 뒤에는 추가 데이터를 위한 최소 aAllocSize 바이트의 공간을 할당합니다.

이러한 사용법은 애플리케이션 레이어 메시지에 PacketBuffer를 할당할 때 가장 적합합니다.

세부정보
매개변수
[in] aAvailableSize
커서 뒤에 할당할 옥텟의 수입니다.
반환
성공 시 할당된 블록의 PacketBuffer를 가리키는 포인터입니다. 실패 시 NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

헤더의 경우 페이로드에 aReservedSize바이트 이상, 초기 커서 포인터 뒤에는 추가 데이터를 위한 aAllocSize바이트 이상의 공간이 있는 PacketBuffer 객체를 할당합니다.

세부정보
매개변수
[in] aReservedSize
커서 뒤에 예약할 옥텟의 수입니다.
[in] aAvailableSize
커서 뒤에 할당할 옥텟의 수입니다.
반환
성공 시 할당된 블록의 PacketBuffer를 가리키는 포인터입니다. 실패 시 NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

해당하는 경우 지정된 버퍼를 적절한 크기의 버퍼에 복사합니다.

이 함수는 소켓에서 작동하지 않습니다.

세부정보
매개변수
[in] aPacket
- 버퍼 또는 버퍼 체인.
반환
새 패킷 버퍼 또는 원래 버퍼