nl::Weave::TLV::TLVUpdater

#include <src/lib/core/WeaveTLV.h>

Cung cấp giao diện Người đọc/Người ghi hợp nhất để chỉnh sửa/thêm/xoá các phần tử trong bộ mã hoá TLV.

Tóm tắt

TLVUpdater là sự kết hợp giữa các đối tượng TLVReader và TLVWriter và cung cấp các phương thức giao diện để chỉnh sửa/xoá dữ liệu trong một bộ mã hoá cũng như thêm các phần tử mới vào bộ mã hoá TLV. Đối tượng TLVUpdater về cơ bản hoạt động như hai con trỏ, một con trỏ để đọc phương thức mã hoá hiện có và một con để ghi (để sao chép dữ liệu hiện có hoặc ghi dữ liệu mới).

Về mặt ngữ nghĩa, đối tượng TLVUpdater hoạt động như một phần kết hợp giữa TLVReader và TLVWriter. Các phương thức TLVUpdater có ý nghĩa tương tự như các phương thức có tên tương tự trong TLVReader/TLVWriter. Nếu có sự khác biệt về ngữ nghĩa, sự khác biệt sẽ được ghi lại rõ ràng trong phần nhận xét của hàm trong WeaveTLVUpdater.cpp.

Một lưu ý đặc biệt quan trọng về phương thức PutBytes() và PutString() của TLVUpdater là có thể để chế độ mã hoá ở trạng thái bị hỏng chỉ có tiêu đề phần tử được ghi khi xảy ra tràn. Các ứng dụng có thể gọi GetRemainingFreeLength() để đảm bảo có khoảng đủ dung lượng trống để viết mã hóa. Lưu ý rằng GetRemainingFreeLength() chỉ cho bạn biết các byte trống hiện có và không có cách nào để ứng dụng biết được độ dài của dữ liệu mã hoá đã được ghi. Trong trường hợp bị tràn, cả PutBytes() và PutString() đều sẽ trả về WEAVE_ERROR_BUFFER_TOO_FILTER cho phương thức gọi.

Ngoài ra, xin lưu ý rằng phương thức Next() bị quá tải để bỏ qua phần tử hiện tại và chuyển trình đọc nội bộ sang phần tử tiếp theo. Vì việc bỏ qua các phần tử đã được mã hoá đòi hỏi phải thay đổi các biến trạng thái không gian trống của trình ghi nội bộ để tính đến không gian được giải phóng mới (có sẵn bằng cách bỏ qua), ứng dụng dự kiến sẽ gọi Next() trên trình cập nhật sau phương thức Get() có giá trị mà nó không muốn ghi lại (tương đương với việc bỏ qua phần tử hiện tại).

Hàm công khai
CopyElement(TLVReader & reader)
CopyElement(uint64_t tag, TLVReader & reader)
DupBytes(uint8_t *& buf, uint32_t & dataLen)
DupString(char *& buf)
EndContainer(TLVType outerContainerType)
EnterContainer(TLVType & outerContainerType)
Chuẩn bị một đối tượng TLVUpdater để đọc các thành phần của vùng chứa.
ExitContainer(TLVType outerContainerType)
Hoàn tất việc đọc phần tử vùng chứa TLV và mã hoá phần cuối của phần tử TLV trong TLV đầu ra.
Finalize(void)
Get(bool & v)
Get(int8_t & v)
Get(int16_t & v)
Get(int32_t & v)
Get(int64_t & v)
Get(uint8_t & v)
Get(uint16_t & v)
Get(uint32_t & v)
Get(uint64_t & v)
Get(float & v)
Get(double & v)
GetBytes(uint8_t *buf, uint32_t bufSize)
GetContainerType(void) const
GetDataPtr(const uint8_t *& data)
GetImplicitProfileId(void)
uint32_t
GetLength(void) const
uint32_t
GetLengthRead(void) const
uint32_t
GetLengthWritten(void)
uint32_t
GetReader(TLVReader & containerReader)
void
GetRemainingFreeLength(void)
uint32_t
GetRemainingLength(void) const
uint32_t
GetString(char *buf, uint32_t bufSize)
GetTag(void) const
uint64_t
GetType(void) const
Init(uint8_t *buf, uint32_t dataLen, uint32_t maxLen)
Khởi động một đối tượng TLVUpdater để chỉnh sửa một vùng đệm đầu vào.
Init(TLVReader & aReader, uint32_t freeLen)
Khởi động một đối tượng TLVUpdater bằng TLVReader.
Move(void)
Sao chép phần tử hiện tại từ đầu vào TLV thành đầu ra TLV.
MoveUntilEnd(void)
void
Di chuyển mọi thứ từ điểm đọc hiện tại của TLVUpdater cho đến khi kết thúc vùng đệm TLV đầu vào sang đầu ra.
Next(void)
Bỏ qua phần tử hiện tại và chuyển đối tượng TLVUpdater đến phần tử tiếp theo trong TLV đầu vào.
Put(uint64_t tag, int8_t v)
Put(uint64_t tag, int16_t v)
Put(uint64_t tag, int32_t v)
Put(uint64_t tag, int64_t v)
Put(uint64_t tag, uint8_t v)
Put(uint64_t tag, uint16_t v)
Put(uint64_t tag, uint32_t v)
Put(uint64_t tag, uint64_t v)
Put(uint64_t tag, int8_t v, bool preserveSize)
Put(uint64_t tag, int16_t v, bool preserveSize)
Put(uint64_t tag, int32_t v, bool preserveSize)
Put(uint64_t tag, int64_t v, bool preserveSize)
Put(uint64_t tag, uint8_t v, bool preserveSize)
Put(uint64_t tag, uint16_t v, bool preserveSize)
Put(uint64_t tag, uint32_t v, bool preserveSize)
Put(uint64_t tag, uint64_t v, bool preserveSize)
Put(uint64_t tag, float v)
Put(uint64_t tag, double v)
PutBoolean(uint64_t tag, bool v)
PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)
PutNull(uint64_t tag)
PutString(uint64_t tag, const char *buf)
PutString(uint64_t tag, const char *buf, uint32_t len)
SetImplicitProfileId(uint32_t profileId)
void
Đặt mã hồ sơ ngầm ẩn cho đối tượng TLVUpdater.
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
VerifyEndOfContainer(void)

Hàm công khai

CopyElement

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

CopyElement

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

DupString

WEAVE_ERROR DupString(
  char *& buf
)

EndContainer

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

Chuẩn bị một đối tượng TLVUpdater để đọc các thành phần của vùng chứa.

Mã này cũng mã hoá phần đầu của đối tượng vùng chứa trong đầu ra TLV.

Phương thức EnterContainer() chuẩn bị đối tượng TLVUpdater hiện tại để bắt đầu đọc các phần tử thành phần của vùng chứa TLV (cấu trúc, mảng hoặc đường dẫn). Đối với mọi lệnh gọi đến ứng dụng EnterContainer() đều phải thực hiện lệnh gọi tương ứng đến ExitContainer().

Khi EnterContainer() được gọi, thì trình đọc của TLVUpdater phải được đặt trên phần tử vùng chứa. Phương thức này lấy đối số tham chiếu đến một giá trị TLVType sẽ được dùng để lưu ngữ cảnh của trình cập nhật trong khi đang đọc vùng chứa.

Khi phương thức EnterContainer() trả về, trình cập nhật sẽ được đặt ngay trước thành phần đầu tiên của vùng chứa. Việc liên tục gọi Next() sẽ chuyển trình cập nhật thông qua các thành viên của tập hợp cho đến khi đạt đến điểm cuối. Tại thời điểm đó, trình cập nhật sẽ trả về WEAVE_END_OF_TLV.

Sau khi đọc xong vùng chứa, ứng dụng có thể tiếp tục đọc các phần tử sau vùng chứa đó bằng cách gọi phương thức ExitContainer().

Thông tin chi tiết
Các tham số
[out] outerContainerType
Tham chiếu đến một giá trị TLVType sẽ nhận ngữ cảnh của trình cập nhật.
Giá trị trả về
WEAVE_NO_ERROR
Nếu phương thức thành công.
WEAVE_ERROR_INCORRECT_STATE
Nếu trình đọc TLVUpdater chưa được định vị trên phần tử vùng chứa.
other
Mọi mã lỗi khác của Weave hoặc nền tảng do TLVWriter::StartContainer() hoặc TLVReader::EnterContainer() trả về.

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Hoàn tất việc đọc phần tử vùng chứa TLV và mã hoá phần cuối của phần tử TLV trong TLV đầu ra.

Phương thức ExitContainer() khôi phục trạng thái của đối tượng TLVUpdater sau lệnh gọi đến EnterContainer(). Đối với mọi lệnh gọi đến ứng dụng EnterContainer(), phải thực hiện lệnh gọi tương ứng đến ExitContainer(), truyền giá trị ngữ cảnh mà phương thức EnterContainer() trả về.

Khi ExitContainer() trả về, trình đọc TLVUpdater sẽ được đặt ngay trước phần tử đầu tiên theo sau vùng chứa trong TLV đầu vào. Từ thời điểm này, các ứng dụng có thể gọi Next() để tiến qua mọi phần tử còn lại.

Sau khi gọi EnterContainer(), các ứng dụng có thể gọi ExitContainer() trên trình cập nhật tại bất kỳ thời điểm nào, bất kể tất cả các phần tử trong vùng chứa cơ bản đã được đọc hay chưa. Ngoài ra, xin lưu ý rằng việc gọi ExitContainer() trước khi đọc tất cả các phần tử trong vùng chứa, sẽ khiến vùng chứa cập nhật bị cắt bớt trong TLV đầu ra.

Thông tin chi tiết
Các tham số
[in] outerContainerType
Giá trị TLVType được phương thức EnterContainer() trả về.
Giá trị trả về
WEAVE_NO_ERROR
Nếu phương thức thành công.
WEAVE_ERROR_TLV_UNDERRUN
Nếu quá trình mã hoá TLV cơ bản kết thúc sớm.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Nếu trình cập nhật gặp loại phần tử TLV không hợp lệ hoặc không được hỗ trợ.
WEAVE_ERROR_INVALID_TLV_TAG
Nếu trình cập nhật gặp phải thẻ TLV trong ngữ cảnh không hợp lệ.
other
Mọi mã lỗi khác của Weave hoặc nền tảng do TLVWriter::EndContainer() hoặc TLVReader::ExitContainer() trả về.

Hoàn tất

WEAVE_ERROR Finalize(
  void
)

Get

WEAVE_ERROR Get(
  bool & v
)

Get

WEAVE_ERROR Get(
  int8_t & v
)

Get

WEAVE_ERROR Get(
  int16_t & v
)

Get

WEAVE_ERROR Get(
  int32_t & v
)

Get

WEAVE_ERROR Get(
  int64_t & v
)

Get

WEAVE_ERROR Get(
  uint8_t & v
)

Get

WEAVE_ERROR Get(
  uint16_t & v
)

Get

WEAVE_ERROR Get(
  uint32_t & v
)

Get

WEAVE_ERROR Get(
  uint64_t & v
)

Get

WEAVE_ERROR Get(
  float & v
)

Get

WEAVE_ERROR Get(
  double & v
)

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

GetContainerType

TLVType GetContainerType(
  void
) const

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

GetImplicitProfileId

uint32_t GetImplicitProfileId(
  void
)

GetLength

uint32_t GetLength(
  void
) const

GetLengthRead

uint32_t GetLengthRead(
  void
) const

GetLengthWritten

uint32_t GetLengthWritten(
  void
)

GetReader

void GetReader(
  TLVReader & containerReader
)

GetRemainingFreeLength

uint32_t GetRemainingFreeLength(
  void
)

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

GetTag

uint64_t GetTag(
  void
) const

GetType

TLVType GetType(
  void
) const

Bắt đầu

WEAVE_ERROR Init(
  uint8_t *buf,
  uint32_t dataLen,
  uint32_t maxLen
)

Khởi động một đối tượng TLVUpdater để chỉnh sửa một vùng đệm đầu vào.

Khi gọi phương thức này, dữ liệu TLV trong vùng đệm sẽ được chuyển đến cuối vùng đệm và một đối tượng TLVReader riêng tư sẽ được khởi chạy trên vùng đệm đã di chuyển này. Một đối tượng TLVWriter riêng tư cũng được khởi chạy trên không gian trống hiện có sẵn ở đầu. Các ứng dụng có thể sử dụng đối tượng TLVUpdater để phân tích cú pháp dữ liệu TLV và sửa đổi/xoá các phần tử hiện có hoặc thêm các phần tử mới vào phương thức mã hoá.

Thông tin chi tiết
Các tham số
[in] buf
Con trỏ đến vùng đệm chứa dữ liệu TLV sẽ được chỉnh sửa.
[in] dataLen
Độ dài của dữ liệu TLV trong vùng đệm.
[in] maxLen
Tổng chiều dài của vùng đệm.
Giá trị trả về
WEAVE_NO_ERROR
Nếu phương thức thành công.
WEAVE_ERROR_INVALID_ARGUMENT
Nếu địa chỉ vùng đệm không hợp lệ.
WEAVE_ERROR_BUFFER_TOO_SMALL
Nếu vùng đệm quá nhỏ.

Bắt đầu

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

Khởi động một đối tượng TLVUpdater bằng TLVReader.

Khi gọi phương thức này, dữ liệu TLV trong vùng đệm được TLVReader trỏ đến sẽ được di chuyển từ điểm đọc hiện tại đến cuối vùng đệm. Một đối tượng TLVReader riêng tư mới được khởi động để đọc từ vị trí mới này, trong khi một đối tượng TLVWriter riêng tư mới được khởi động để ghi vào không gian bộ đệm được giải phóng.

Lưu ý rằng nếu TLVReader đã được định vị "trên" một phần tử, thì trước tiên, phần tử này sẽ được sao lưu vào đầu của phần tử đó. Cũng xin lưu ý rằng tính năng sao lưu này hoạt động tốt với các phần tử vùng chứa, tức là nếu TLVReader đã được dùng để gọi EnterContainer(), thì không có gì để sao lưu. Nhưng nếu TLVReader được định vị trên phần tử vùng chứa và EnterContainer() chưa được gọi, thì đối tượng TLVReader được sao lưu vào đầu đầu vùng chứa.

Đối tượng TLVReader đã nhập sẽ bị huỷ trước khi trả về và ứng dụng không được sử dụng cùng một đối tượng khi trả về.

Thông tin chi tiết
Các tham số
[in,out] aReader
Tham chiếu đến một đối tượng TLVReader sẽ bị huỷ trước khi trả về.
[in] freeLen
Độ dài không gian trống (tính bằng byte) có trong vùng đệm dữ liệu được mã hoá trước.
Giá trị trả về
WEAVE_NO_ERROR
Nếu phương thức thành công.
WEAVE_ERROR_INVALID_ARGUMENT
Nếu địa chỉ vùng đệm không hợp lệ.
WEAVE_ERROR_NOT_IMPLEMENTED
Liệu trình đọc có được khởi chạy trên một chuỗi vùng đệm hay không.

Di chuyển

WEAVE_ERROR Move(
  void
)

Sao chép phần tử hiện tại từ đầu vào TLV thành đầu ra TLV.

Phương thức Move() sao chép phần tử hiện tại mà trên đó trình đọc của TLVUpdater sẽ được đặt vào trình ghi của TLVUpdater. Ứng dụng nên gọi Next() và định vị trình đọc của TLVUpdater trên một phần tử trước khi gọi phương thức này. Giống như phương thức TLVReader::Next(), nếu trình đọc được đặt trên phần tử vùng chứa tại thời điểm gọi, tất cả thành phần của vùng chứa sẽ được sao chép. Nếu trình đọc không được định vị trên bất kỳ phần tử nào thì sẽ không có gì thay đổi khi gọi phương thức này.

Thông tin chi tiết
Giá trị trả về
WEAVE_NO_ERROR
Nếu trình đọc TLVUpdater đã được định vị thành công trên một phần tử mới.
WEAVE_END_OF_TLV
Nếu trình đọc của TLVUpdater đang trỏ đến cuối vùng chứa.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Nếu trình đọc của TLVIpdater không được định vị trên phần tử TLV hợp lệ.
other
Trả về các mã lỗi khác do phương thức TLVReader::Skip() trả về.

MoveUntilEnd

void MoveUntilEnd(
  void
)

Di chuyển mọi thứ từ điểm đọc hiện tại của TLVUpdater cho đến khi kết thúc vùng đệm TLV đầu vào sang đầu ra.

Phương thức này hỗ trợ di chuyển mọi thứ từ điểm đọc hiện tại của TLVUpdater cho đến cuối vùng đệm của trình đọc sang trình ghi của TLVUpdater.

Tiếp theo

WEAVE_ERROR Next(
  void
)

Bỏ qua phần tử hiện tại và chuyển đối tượng TLVUpdater đến phần tử tiếp theo trong TLV đầu vào.

Phương thức Next() bỏ qua phần tử hiện tại trong TLV đầu vào và chuyển trình đọc của TLVUpdater sang phần tử tiếp theo nằm trong cùng ngữ cảnh vùng chứa. Cụ thể, nếu trình đọc được đặt ở cấp bên ngoài nhất của bộ mã hoá TLV, thì lệnh gọi Next() sẽ chuyển trình đọc đến phần tử tiếp theo, ở trên cùng. Nếu trình đọc được đặt trong phần tử vùng chứa TLV (cấu trúc, mảng hoặc đường dẫn), thì việc gọi Next() sẽ chuyển phần tử này đến phần tử thành phần tiếp theo của vùng chứa.

Vì Next() ràng buộc chuyển động của người đọc với ngữ cảnh vùng chứa hiện tại, nên việc gọi Next() khi trình đọc được định vị trên một phần tử vùng chứa sẽ qua vùng chứa, bỏ qua các phần tử thành phần (và các thành phần của bất kỳ vùng chứa lồng nhau nào) cho đến khi tới phần tử đầu tiên sau vùng chứa.

Khi không có thêm phần tử nào trong ngữ cảnh vùng chứa cụ thể, phương thức Next() sẽ trả về lỗi WEAVE_END_OF_TLV và vị trí của trình đọc sẽ không thay đổi.

Thông tin chi tiết
Giá trị trả về
WEAVE_NO_ERROR
Nếu trình đọc TLVUpdater đã được định vị thành công trên một phần tử mới.
other
Trả về mã lỗi Weave hoặc mã lỗi nền tảng mà phương thức TLVReader::Skip() và TLVReader::Next() trả về.

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v,
  bool preserveSize
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

Đặt

WEAVE_ERROR Put(
  uint64_t tag,
  double v
)

PutBoolean

WEAVE_ERROR PutBoolean(
  uint64_t tag,
  bool v
)

PutBytes

WEAVE_ERROR PutBytes(
  uint64_t tag,
  const uint8_t *buf,
  uint32_t len
)

PutNull

WEAVE_ERROR PutNull(
  uint64_t tag
)

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf
)

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf,
  uint32_t len
)

SetImplicitProfileId

void SetImplicitProfileId(
  uint32_t profileId
)

Đặt mã hồ sơ ngầm ẩn cho đối tượng TLVUpdater.

Phương thức này đặt mã nhận dạng hồ sơ ngầm ẩn cho đối tượng TLVUpdater. Khi trình cập nhật được yêu cầu mã hoá một phần tử mới, nếu mã hồ sơ của thẻ liên kết với phần tử mới khớp với giá trị của profileId, thì trình cập nhật sẽ mã hoá thẻ ở dạng ngầm ẩn, do đó bỏ qua mã hồ sơ trong quá trình này.

Thông tin chi tiết
Các tham số
[in] profileId
Id hồ sơ của thẻ phải được mã hoá dưới dạng ngầm ẩn.

StartContainer

WEAVE_ERROR StartContainer(
  uint64_t tag,
  TLVType containerType,
  TLVType & outerContainerType
)

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)