nl::Weave::TLV::TLVUpdater

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

Bietet eine einheitliche Reader/Writer-Schnittstelle zum Bearbeiten, Hinzufügen und Löschen von Elementen in TLV-Codierung.

Zusammenfassung

Der TLVUpdater ist eine Vereinigung der TLVReader- und TLVWriter-Objekte und bietet Schnittstellenmethoden zum Bearbeiten/Löschen von Daten in einer Codierung sowie zum Hinzufügen neuer Elemente zur TLV-Codierung. Das TLVUpdater-Objekt agiert im Wesentlichen wie zwei Cursor: einen zum Lesen vorhandener Codierung und einen zum Schreiben (entweder zum Kopieren vorhandener Daten oder zum Schreiben neuer Daten).

Semantisch funktioniert das TLVUpdater-Objekt wie eine Kombination aus TLVReader und TLVWriter. Die TLVUpdater-Methoden haben mehr oder weniger ähnliche Bedeutungen wie ähnlich benannte Gegenstücke in TLVReader/TLVWriter. Wo es Unterschiede in der Semantik gibt, werden diese im Kommentarabschnitt der Funktion in WeaveTLVUpdater.cpp klar dokumentiert.

Ein besonders wichtiger Hinweis bei den PutBytes()- und PutString()-Methoden des TLVUpdater besteht darin, dass bei einem Überlauf die Codierung in einem beschädigten Zustand belassen werden kann. Nur der Element-Header wird geschrieben. Anwendungen können GetRemainingFreeLength() aufrufen, um sicherzustellen, dass ungefähr genügend freier Speicherplatz zum Schreiben der Codierung vorhanden ist. Beachten Sie, dass GetRemainingFreeLength() Ihnen nur die verfügbaren kostenlosen Byte mitteilt und dass die Anwendung keine Möglichkeit hat, die Länge der codierten Daten zu ermitteln, die geschrieben werden. Im Fall eines Überlaufs geben sowohl PutBytes() als auch PutString() WEAVE_ERROR_BUFFER_TOO_small an den Aufrufer zurück.

Beachten Sie außerdem, dass die Methode Next() überlastet ist, sodass das aktuelle Element übersprungen und der interne Leser zum nächsten Element weitergeleitet wird. Da zum Überspringen bereits codierter Elemente die Variablen für den kostenlosen Bereich des Autors geändert werden müssen, um den neuen freigegebenen Bereich zu berücksichtigen, der durch Überspringen verfügbar gemacht wird, wird erwartet, dass die Anwendung im Updater nach einer Get()-Methode Next() aufruft, deren Wert nicht zurückgeschrieben werden soll. Dies entspricht dem Überspringen des aktuellen Elements.

Öffentliche Funktionen

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)
Bereitet ein TLVUpdater-Objekt zum Lesen der Elemente eines Containers vor.
ExitContainer(TLVType outerContainerType)
Führt das Lesen eines TLV-Containerelements durch und codiert ein Ende des TLV-Elements in der TLV-Ausgabe.
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)
Initialisieren Sie ein TLVUpdater-Objekt, um einen einzelnen Eingabezwischenspeicher zu bearbeiten.
Init(TLVReader & aReader, uint32_t freeLen)
Initialisieren Sie ein TLVUpdater-Objekt mit einem TLVReader.
Move(void)
Kopiert das aktuelle Element aus der Eingabe-TLV in die Ausgabe TLV.
MoveUntilEnd(void)
void
Verschieben Sie alles vom aktuellen Lesepunkt des TLVUpdater bis zum Ende des Eingabezwischenspeichers TLV in die Ausgabe.
Next(void)
Überspringt das aktuelle Element und bewegt das TLVUpdater-Objekt zum nächsten Element in der Eingabe-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
Legen Sie die implizite Profil-ID für das TLVUpdater-Objekt fest.
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
VerifyEndOfContainer(void)

Öffentliche Funktionen

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
)

Bereitet ein TLVUpdater-Objekt zum Lesen der Elemente eines Containers vor.

Außerdem codiert sie den Anfang eines Containerobjekts in der Ausgabe-TLV.

Die EnterContainer()-Methode bereitet das aktuelle TLVUpdater-Objekt vor, damit die Mitgliederelemente eines TLV-Containers (eine Struktur, ein Array oder ein Pfad) gelesen werden können. Für jeden Aufruf von EnterContainer()-Anwendungen muss ein entsprechender Aufruf an ExitContainer() erfolgen.

Wenn EnterContainer() aufgerufen wird, muss der Reader des TLVUpdater auf dem Containerelement positioniert werden. Die Methode übernimmt als Argument einen Verweis auf einen TLVType -Wert, mit dem der Kontext des Updaters gespeichert wird, während er den Container liest.

Wenn die Methode EnterContainer() zurückgegeben wird, wird der Updater direkt vor dem ersten Mitglied des Containers platziert. Durch wiederholtes Aufrufen von Next() wird der Updater durch die Mitglieder der Sammlung geleitet, bis das Ende erreicht ist. Zu diesem Zeitpunkt gibt der Updater WEAVE_END_OF_TLV zurück.

Sobald die Anwendung das Lesen eines Containers abgeschlossen hat, kann sie durch Aufrufen der Methode ExitContainer() nach dem Container weitere Elemente lesen.

Details
Parameter
[out] outerContainerType
Ein Verweis auf einen TLVType-Wert, der den Kontext des Updaters empfängt.
Rückgabewerte
WEAVE_NO_ERROR
Gibt an, ob die Methode erfolgreich war.
WEAVE_ERROR_INCORRECT_STATE
Wenn der TLVUpdater-Reader nicht auf einem Containerelement positioniert ist.
other
Jeder andere Weave- oder Plattform-Fehlercode, der von TLVWriter::StartContainer() oder TLVReader::EnterContainer() zurückgegeben wird.

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Führt das Lesen eines TLV-Containerelements durch und codiert ein Ende des TLV-Elements in der TLV-Ausgabe.

Die Methode ExitContainer() stellt den Status eines TLVUpdater-Objekts nach einem Aufruf von EnterContainer() wieder her. Für jeden Aufruf von EnterContainer()-Anwendungen muss ein entsprechender Aufruf an ExitContainer() erfolgen und der von der Methode EnterContainer() zurückgegebene Kontextwert übergeben werden.

Wenn ExitContainer() zurückgegeben wird, wird der TLVUpdater-Reader direkt vor dem ersten Element platziert, das im Eingabe-TLV auf den Container folgt. Ab diesem Zeitpunkt können Anwendungen Next() aufrufen, um durch alle verbleibenden Elemente zu blättern.

Nach dem Aufruf von EnterContainer() können Anwendungen auf dem Updater jederzeit ExitContainer() aufrufen, unabhängig davon, ob alle Elemente im zugrunde liegenden Container gelesen wurden. Beachten Sie außerdem, dass ein Aufruf von ExitContainer() vor dem Lesen aller Elemente im Container dazu führt, dass der aktualisierte Container in der TLV-Ausgabe abgeschnitten wird.

Details
Parameter
[in] outerContainerType
Der TLVType-Wert, der von der EnterContainer()-Methode zurückgegeben wurde.
Rückgabewerte
WEAVE_NO_ERROR
Gibt an, ob die Methode erfolgreich war.
WEAVE_ERROR_TLV_UNDERRUN
Wenn die zugrunde liegende TLV-Codierung vorzeitig beendet wird.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Wenn der Updater auf einen ungültigen oder nicht unterstützten TLV-Elementtyp gestoßen ist.
WEAVE_ERROR_INVALID_TLV_TAG
Der Updater ist auf ein TLV-Tag in einem ungültigen Kontext gestoßen.
other
Jeder andere Weave- oder Plattform-Fehlercode, der von TLVWriter::EndContainer() oder TLVReader::ExitContainer() zurückgegeben wird.

Abschließen

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 

Init

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

Initialisieren Sie ein TLVUpdater-Objekt, um einen einzelnen Eingabezwischenspeicher zu bearbeiten.

Beim Aufrufen dieser Methode werden die TLV-Daten im Zwischenspeicher an das Ende des Puffers verschoben und ein privates TLVReader-Objekt wird auf diesem verschobenen Zwischenspeicher initialisiert. Ein privates TLVWriter-Objekt wird ebenfalls auf dem freien Speicherplatz initialisiert, der jetzt zu Beginn verfügbar ist. Anwendungen können das Objekt TLVUpdater verwenden, um die TLV-Daten zu parsen und vorhandene Elemente zu ändern/zu löschen oder neue Elemente zur Codierung hinzuzufügen.

Details
Parameter
[in] buf
Ein Zeiger auf einen Puffer, der die zu bearbeitenden TLV-Daten enthält.
[in] dataLen
Die Länge der TLV-Daten im Puffer.
[in] maxLen
Die Gesamtlänge des Puffers.
Rückgabewerte
WEAVE_NO_ERROR
Gibt an, ob die Methode erfolgreich war.
WEAVE_ERROR_INVALID_ARGUMENT
Wenn die Pufferadresse ungültig ist.
WEAVE_ERROR_BUFFER_TOO_SMALL
Wenn der Puffer zu klein ist.

Init

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

Initialisieren Sie ein TLVUpdater-Objekt mit einem TLVReader.

Beim Aufrufen dieser Methode werden die TLV-Daten im Zwischenspeicher, auf die der TLVReader verweist, vom aktuellen Lesepunkt zum Ende des Zwischenspeichers verschoben. Ein neues privates TLVReader-Objekt wird initialisiert, um aus diesem neuen Speicherort zu lesen, während ein neues privates TLVWriter-Objekt initialisiert wird, um in den freigegebenen Zwischenspeicherbereich zu schreiben.

Wenn sich TLVReader bereits "auf" einem Element befindet, wird er zuerst am Anfang dieses Elements zurückgestellt. Beachten Sie auch, dass diese Sicherung gut bei Containerelementen funktioniert. Wenn z. B. TLVReader bereits zum Aufrufen von EnterContainer() verwendet wurde, gibt es nichts für einen Backoff. Wenn jedoch TLVReader auf dem Containerelement positioniert war und EnterContainer() noch nicht aufgerufen wurde, wird das TLVReader-Objekt am Anfang des Container-Heads zurückgestellt.

Das Eingabeobjekt TLVReader wird vor der Rückgabe zerstört und die Anwendung darf dasselbe bei der Rückgabe nicht verwenden.

Details
Parameter
[in,out] aReader
Verweis auf ein TLVReader-Objekt, das vor der Rückgabe zerstört wird.
[in] freeLen
Die Länge des freien Speicherplatzes (in Byte), der im vorcodierten Datenpuffer verfügbar ist.
Rückgabewerte
WEAVE_NO_ERROR
Gibt an, ob die Methode erfolgreich war.
WEAVE_ERROR_INVALID_ARGUMENT
Wenn die Pufferadresse ungültig ist.
WEAVE_ERROR_NOT_IMPLEMENTED
Wenn der Reader durch eine Kette von Puffern initialisiert wurde.

Verschieben

WEAVE_ERROR Move(
  void
)

Kopiert das aktuelle Element aus der Eingabe-TLV in die Ausgabe TLV.

Die Methode Move() kopiert das aktuelle Element, auf dem sich der TLVUpdater-Reader befindet, in den Writer des TLVUpdater. Die Anwendung sollte Next() aufrufen und das Lesegerät des TLVUpdater auf einem Element positionieren, bevor diese Methode aufgerufen wird. Wenn sich der Reader wie bei der TLVReader::Next()-Methode zum Zeitpunkt des Aufrufs auf einem Containerelement befindet, werden alle Mitglieder des Containers kopiert. Wenn sich der Reader nicht auf einem Element befindet, ändert sich am Aufruf dieser Methode nichts.

Details
Rückgabewerte
WEAVE_NO_ERROR
Der TLVUpdater-Reader wurde erfolgreich auf einem neuen Element positioniert.
WEAVE_END_OF_TLV
Wenn das Lesegerät des TLVUpdater auf das Ende des Containers zeigt.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Das Lesegerät des TLVIpdater befindet sich nicht in einem gültigen TLV-Element.
other
Gibt andere Fehlercodes zurück, die von der TLVReader::Skip()-Methode zurückgegeben werden.

MoveUntilEnd

void MoveUntilEnd(
  void
)

Verschieben Sie alles vom aktuellen Lesepunkt des TLVUpdater bis zum Ende des Eingabezwischenspeichers TLV in die Ausgabe.

Diese Methode unterstützt das Verschieben aller Elemente vom aktuellen Lesepunkt des TLVUpdater bis zum Ende des Lesepuffers in den Writer des TLVUpdater.

Weiter

WEAVE_ERROR Next(
  void
)

Überspringt das aktuelle Element und bewegt das TLVUpdater-Objekt zum nächsten Element in der Eingabe-TLV.

Die Methode Next() überspringt das aktuelle Element in der Eingabe-TLV und leitet den Leser des TLVUpdater zum nächsten Element weiter, das sich im selben Begrenzungskontext befindet. Insbesondere wenn sich der Reader auf der äußeren Ebene einer TLV-Codierung befindet, wird durch das Aufrufen von Next() zum nächsten, obersten Element gewechselt. Wenn sich das Lesegerät innerhalb eines TLV-Containerelements (einer Struktur, eines Arrays oder eines Pfads) befindet, gelangen Sie durch Aufrufen von Next() zum nächsten Elementelement des Containers.

Da Next() die Lesebewegung auf den aktuellen Begrenzungskontext einschränkt, wird beim Aufrufen von Next(), wenn sich der Leser auf einem Containerelement befindet, über den Container bewegt. Dabei werden seine Mitgliederelemente (und die Mitglieder aller verschachtelten Container) übersprungen, bis das erste Element nach dem Container erreicht ist.

Wenn in einem bestimmten Begrenzungskontext keine weiteren Elemente vorhanden sind, gibt die Next()-Methode einen WEAVE_END_OF_TLV-Fehler zurück und die Position des Lesers bleibt unverändert.

Details
Rückgabewerte
WEAVE_NO_ERROR
Der TLVUpdater-Reader wurde erfolgreich auf einem neuen Element positioniert.
other
Gibt die Weave- oder Plattform-Fehlercodes zurück, die von den Methoden TLVReader::Skip() und TLVReader::Next() zurückgegeben werden.

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

Best Practices

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

Best Practices

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

Best Practices

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

Best Practices

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

Best Practices

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

Best Practices

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

Best Practices

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

Best Practices

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

Best Practices

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

Best Practices

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
)

Legen Sie die implizite Profil-ID für das TLVUpdater-Objekt fest.

Diese Methode legt die implizite Profil-ID für das Objekt TLVUpdater fest. Wenn der Updater aufgefordert wird, ein neues Element zu codieren, und die Profil-ID des Tags, das mit dem neuen Element verknüpft ist, mit dem Wert von profileId übereinstimmt, codiert der Updater das Tag implizit. Die Profil-ID wird dabei weggelassen.

Details
Parameter
[in] profileId
Die Profil-ID von Tags, die implizit codiert werden sollten.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)