nl::Weave::TLV::TLVUpdater

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

Menyediakan antarmuka Pembaca/Penulis terpadu untuk mengedit/menambahkan/menghapus elemen dalam encoding TLV.

Ringkasan

TLVUpdater adalah gabungan objek TLVReader dan TLVWriter dan menyediakan metode antarmuka untuk mengedit/menghapus data dalam encoding serta menambahkan elemen baru ke encoding TLV. Objek TLVUpdater pada dasarnya berfungsi seperti dua kursor, satu untuk membaca encoding yang ada dan satu lagi untuk menulis (untuk menyalin data yang ada atau menulis data baru).

Secara semantik, objek TLVUpdater berfungsi seperti gabungan dari TLVReader dan TLVWriter. Metode TLVUpdater memiliki arti yang kurang lebih sama dengan metode yang memiliki nama serupa di TLVReader/TLVWriter. Jika ada perbedaan dalam semantik, perbedaan tersebut didokumentasikan dengan jelas di bagian komentar fungsi di WeaveTLVUpdater.cpp.

Satu catatan yang sangat penting tentang metode PutBytes() dan PutString() TLVUpdater adalah bahwa metode ini dapat membiarkan encoding dalam keadaan rusak dengan hanya header elemen yang ditulis saat terjadi overflow. Aplikasi dapat memanggil GetRemainingFreeLength() untuk memastikan kira-kira ada cukup ruang kosong untuk menulis encoding. Perhatikan bahwa GetRemainingFreeLength() hanya memberi tahu Anda byte gratis yang tersedia dan tidak cara aplikasi mengetahui panjang data yang dienkode yang akan ditulis. Jika terjadi overflow, PutBytes() dan PutString() akan menampilkan WEAVE_ERROR_BUFFER_TOO_Small ke pemanggil.

Selain itu, perhatikan bahwa metode Next() kelebihan beban untuk melewati elemen saat ini dan juga memajukan pembaca internal ke elemen berikutnya. Karena melewatkan elemen yang sudah dienkode memerlukan perubahan variabel status ruang kosong penulis internal untuk memperhitungkan ruang kosong yang baru (disediakan dengan melewati), aplikasi diharapkan memanggil Next() pada updater setelah metode Get() yang nilainya tidak ingin ditulis kembali (yang setara dengan melewati elemen saat ini).

Fungsi publik
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)
Menyiapkan objek TLVUpdater untuk membaca elemen container.
ExitContainer(TLVType outerContainerType)
Menyelesaikan pembacaan elemen penampung TLV dan mengenkode akhir elemen TLV dalam TLV output.
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)
Lakukan inisialisasi objek TLVUpdater untuk mengedit buffering input tunggal.
Init(TLVReader & aReader, uint32_t freeLen)
Lakukan inisialisasi objek TLVUpdater menggunakan TLVReader.
Move(void)
Menyalin elemen saat ini dari input TLV ke output TLV.
MoveUntilEnd(void)
void
Pindahkan semua dari titik baca TLVUpdater saat ini hingga akhir buffer TLV input ke output.
Next(void)
Lewati elemen saat ini dan lanjutkan objek TLVUpdater ke elemen berikutnya dalam input TLV.
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
Tetapkan ID Profil Implisit untuk objek TLVUpdater.
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
VerifyEndOfContainer(void)

Fungsi publik

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
)

Menyiapkan objek TLVUpdater untuk membaca elemen container.

Kode ini juga mengenkode awal objek container dalam output TLV.

Metode EnterContainer() menyiapkan objek TLVUpdater saat ini untuk mulai membaca elemen anggota penampung TLV (struktur, array, atau jalur). Untuk setiap panggilan ke EnterContainer(), aplikasi harus melakukan panggilan yang sesuai ke ExitContainer().

Saat EnterContainer() dipanggil, pembaca TLVUpdater harus diposisikan di elemen penampung. Metode ini mengambil referensi ke nilai TLVType sebagai argumen yang akan digunakan untuk menyimpan konteks updater saat membaca container.

Saat metode EnterContainer() ditampilkan, updater diposisikan tepat sebelum anggota pertama penampung. Berulang kali memanggil Next() akan memajukan updater melalui anggota koleksi hingga akhir, dan pada saat itu updater akan menampilkan WEAVE_END_OF_TLV.

Setelah selesai membaca container, aplikasi dapat melanjutkan membaca elemen setelah container dengan memanggil metode ExitContainer().

Detail
Parameter
[out] outerContainerType
Referensi ke nilai TLVType yang akan menerima konteks updater.
Nilai Pengembalian
WEAVE_NO_ERROR
Jika metode ini berhasil.
WEAVE_ERROR_INCORRECT_STATE
Jika pembaca TLVUpdater tidak diposisikan pada elemen penampung.
other
Kode error platform atau Weave lain yang ditampilkan oleh TLVWriter::StartContainer() atau TLVReader::EnterContainer().

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Menyelesaikan pembacaan elemen penampung TLV dan mengenkode akhir elemen TLV dalam TLV output.

Metode ExitContainer() memulihkan status objek TLVUpdater setelah panggilan ke EnterContainer(). Untuk setiap panggilan ke EnterContainer(), aplikasi harus melakukan panggilan yang sesuai ke ExitContainer(), dengan meneruskan nilai konteks yang ditampilkan oleh metode EnterContainer().

Saat ExitContainer() ditampilkan, pembaca TLVUpdater diposisikan tepat sebelum elemen pertama yang mengikuti container dalam TLV input. Dari sini, aplikasi dapat memanggil Next() untuk melanjutkan ke elemen yang tersisa.

Setelah EnterContainer() dipanggil, aplikasi dapat memanggil ExitContainer() pada updater kapan saja, terlepas dari apakah semua elemen dalam penampung pokok telah dibaca atau belum. Selain itu, perhatikan bahwa memanggil ExitContainer() sebelum membaca semua elemen dalam container, akan mengakibatkan container yang diperbarui terpotong pada output TLV.

Detail
Parameter
[in] outerContainerType
Nilai TLVType yang ditampilkan oleh metode EnterContainer().
Nilai Pengembalian
WEAVE_NO_ERROR
Jika metode ini berhasil.
WEAVE_ERROR_TLV_UNDERRUN
Jika encoding TLV yang mendasarinya berakhir sebelum waktunya.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Apakah updater mengalami jenis elemen TLV yang tidak valid atau tidak didukung.
WEAVE_ERROR_INVALID_TLV_TAG
Apakah updater menemukan tag TLV dalam konteks yang tidak valid.
other
Kode error platform atau Weave lain yang ditampilkan oleh TLVWriter::EndContainer() atau TLVReader::ExitContainer().

Finalisasi

WEAVE_ERROR Finalize(
  void
)

Dapatkan

WEAVE_ERROR Get(
  bool & v
)

Dapatkan

WEAVE_ERROR Get(
  int8_t & v
)

Dapatkan

WEAVE_ERROR Get(
  int16_t & v
)

Dapatkan

WEAVE_ERROR Get(
  int32_t & v
)

Dapatkan

WEAVE_ERROR Get(
  int64_t & v
)

Dapatkan

WEAVE_ERROR Get(
  uint8_t & v
)

Dapatkan

WEAVE_ERROR Get(
  uint16_t & v
)

Dapatkan

WEAVE_ERROR Get(
  uint32_t & v
)

Dapatkan

WEAVE_ERROR Get(
  uint64_t & v
)

Dapatkan

WEAVE_ERROR Get(
  float & v
)

Dapatkan

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

Inisiasi

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

Lakukan inisialisasi objek TLVUpdater untuk mengedit buffering input tunggal.

Saat memanggil metode ini, data TLV dalam buffer dipindahkan ke akhir buffer dan objek TLVReader pribadi diinisialisasi pada buffer yang direlokasi ini. Objek TLVWriter pribadi juga diinisialisasi pada ruang kosong yang sekarang tersedia di awal. Aplikasi dapat menggunakan objek TLVUpdater untuk mengurai data TLV dan mengubah/menghapus elemen yang ada atau menambahkan elemen baru ke encoding.

Detail
Parameter
[in] buf
Pointer ke buffer yang berisi data TLV yang akan diedit.
[in] dataLen
Panjang data TLV di buffer.
[in] maxLen
Panjang total buffer.
Nilai Pengembalian
WEAVE_NO_ERROR
Jika metode ini berhasil.
WEAVE_ERROR_INVALID_ARGUMENT
Jika alamat buffer tidak valid.
WEAVE_ERROR_BUFFER_TOO_SMALL
Jika buffer terlalu kecil.

Inisiasi

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

Lakukan inisialisasi objek TLVUpdater menggunakan TLVReader.

Saat memanggil metode ini, data TLV dalam buffer yang ditunjuk oleh TLVReader dipindahkan dari titik baca saat ini ke akhir buffer. Objek TLVReader pribadi baru diinisialisasi untuk dibaca dari lokasi baru ini, sedangkan objek TLVWriter pribadi baru diinisialisasi untuk menulis ke ruang buffer yang telah dikosongkan.

Perhatikan bahwa jika TLVReader sudah diposisikan "pada" elemen, elemen tersebut akan di-backup ke awal elemen tersebut. Perhatikan juga bahwa pencadangan ini berfungsi dengan baik dengan elemen container, yaitu, jika TLVReader sudah digunakan untuk memanggil EnterContainer(), maka tidak ada yang dapat dicadangkan. Namun, jika TLVReader diposisikan pada elemen container dan EnterContainer() belum dipanggil, objek TLVReader akan di-back-off ke awal head container.

Objek TLVReader input akan dihancurkan sebelum ditampilkan dan aplikasi tidak boleh menggunakan hal yang sama saat ditampilkan.

Detail
Parameter
[in,out] aReader
Referensi ke objek TLVReader yang akan dihancurkan sebelum ditampilkan.
[in] freeLen
Panjang ruang kosong (dalam byte) yang tersedia dalam buffering data yang dienkode sebelumnya.
Nilai Pengembalian
WEAVE_NO_ERROR
Jika metode ini berhasil.
WEAVE_ERROR_INVALID_ARGUMENT
Jika alamat buffer tidak valid.
WEAVE_ERROR_NOT_IMPLEMENTED
Jika pembaca diinisialisasi pada rantai buffer.

Pindahkan

WEAVE_ERROR Move(
  void
)

Menyalin elemen saat ini dari input TLV ke output TLV.

Metode Move() menyalin elemen saat ini tempat pembaca TLVUpdater berada, ke penulis TLVUpdater. Aplikasi harus memanggil Next() dan memosisikan pembaca TLVUpdater pada elemen sebelum memanggil metode ini. Sama seperti metode TLVReader::Next(), jika pembaca diposisikan pada elemen container pada saat panggilan, semua anggota container akan disalin. Jika pembaca tidak diposisikan pada elemen apa pun, tidak ada yang berubah saat memanggil metode ini.

Detail
Nilai Pengembalian
WEAVE_NO_ERROR
Jika pembaca TLVUpdater berhasil diposisikan di elemen baru.
WEAVE_END_OF_TLV
Jika pembaca TLVUpdater mengarah ke ujung penampung.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Jika pembaca TLVIvider tidak diposisikan pada elemen TLV yang valid.
other
Menampilkan kode error lain yang ditampilkan oleh metode TLVReader::Skip().

MoveUntilEnd

void MoveUntilEnd(
  void
)

Pindahkan semua dari titik baca TLVUpdater saat ini hingga akhir buffer TLV input ke output.

Metode ini mendukung pemindahan semua dari titik baca TLVUpdater saat ini hingga akhir buffering pembaca ke penulis TLVUpdater.

Berikutnya

WEAVE_ERROR Next(
  void
)

Lewati elemen saat ini dan lanjutkan objek TLVUpdater ke elemen berikutnya dalam input TLV.

Metode Next() melewati elemen saat ini dalam input TLV dan memajukan pembaca TLVUpdater ke elemen berikutnya yang berada dalam konteks containment yang sama. Khususnya, jika pembaca diposisikan di tingkat paling luar encoding TLV, memanggil Next() akan memajukannya ke elemen berikutnya yang paling atas. Jika pembaca diposisikan dalam elemen container TLV (struktur, array, atau jalur), memanggil Next() akan memajukannya ke elemen anggota penampung berikutnya.

Karena Next() membatasi gerakan pembaca ke konteks containment saat ini, memanggil Next() saat pembaca diposisikan pada elemen container akan bergerak maju melalui penampung, melewati elemen anggotanya (dan anggota penampung bertingkat) hingga mencapai elemen pertama setelah penampung.

Jika tidak ada elemen lebih lanjut dalam konteks pembatasan tertentu, metode Next() akan menampilkan error WEAVE_END_OF_TLV dan posisi pembaca tidak akan berubah.

Detail
Nilai Pengembalian
WEAVE_NO_ERROR
Jika pembaca TLVUpdater berhasil diposisikan di elemen baru.
other
Menampilkan kode error platform atau Weave yang ditampilkan oleh metode TLVReader::Skip() dan TLVReader::Next().

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

Put

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

Put

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

Put

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

Put

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

Put

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

Put

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

Put

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

Put

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

Put

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

Put

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
)

Tetapkan ID Profil Implisit untuk objek TLVUpdater.

Metode ini menetapkan ID profil implisit untuk objek TLVUpdater. Saat updater diminta untuk mengenkode elemen baru, jika ID profil tag yang terkait dengan elemen baru cocok dengan nilai profileId, updater akan mengenkode tag dalam bentuk implisit, sehingga menghilangkan ID profil dalam prosesnya.

Detail
Parameter
[in] profileId
ID profil tag yang harus dienkode dalam bentuk implisit.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)