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 der TLV-Codierung.

Zusammenfassung

Der TLVUpdater ist eine Kombination der Objekte TLVReader und TLVWriter und bietet Oberflächenmethoden 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 Cursors, einer zum Lesen der vorhandenen Codierung und ein anderer zum Lesen der vorhandenen Codierung (entweder zum Kopieren vorhandener Daten oder zum Schreiben neuer Daten).

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

Ein besonders wichtiger Hinweis zu den PutBytes()- und PutString()-Methoden des TLVUpdater besteht darin, dass bei einem Überlauf nur der Element-Header geschrieben wird, sodass die Codierung beschädigt wird. 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 Bytes anzeigt und die Anwendung keine Möglichkeit hat, die Länge der codierten Daten zu ermitteln, die geschrieben werden. Im Falle eines Überlaufs geben PutBytes() und PutString() WEAVE_ERROR_BUFFER_TOO_small an den Aufrufer zurück.

Beachten Sie außerdem, dass die Methode Next() überlastet ist, um sowohl das aktuelle Element zu überspringen als auch den internen Reader zum nächsten Element weiterzuleiten. Da zum Überspringen bereits codierter Elemente die Zustandsvariablen des internen Autors geändert werden müssen, um den neuen (durch Überspringen zur Verfügung gestellten) kostenlos gewordenen Speicherplatz zu berücksichtigen, wird erwartet, dass die Anwendung Next() im Updater nach einer Get()-Methode 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 von Containerelementen vor.
ExitContainer(TLVType outerContainerType)
Schließt das Lesen eines TLV-Containerelements ab 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 Eingabepuffer zu bearbeiten.
Init(TLVReader & aReader, uint32_t freeLen)
Initialisieren Sie ein TLVUpdater-Objekt mit einem TLVReader.
Move(void)
Kopiert das aktuelle Element aus Eingabe-TLV in Ausgabe-TLV.
MoveUntilEnd(void)
void
Verschiebt alles vom aktuellen Lesepunkt des TLVUpdater bis zum Ende des TLV-Zwischenspeichers der Eingabe in die Ausgabe.
Next(void)
Das aktuelle Element wird übersprungen und das Objekt TLVUpdater zum nächsten Element in der TLV verschoben.
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 Objekt TLVUpdater 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 von Containerelementen vor.

Außerdem wird ein Start des Containerobjekts in der TLV-Ausgabe codiert.

Die Methode EnterContainer() bereitet das aktuelle Objekt TLVUpdater so vor, dass es mit dem Lesen der Mitgliederelemente eines TLV-Containers (einer Struktur, eines Arrays oder eines Pfads) beginnen kann. Bei jedem Aufruf von EnterContainer() müssen Anwendungen einen entsprechenden Aufruf an ExitContainer() senden.

Wenn EnterContainer() aufgerufen wird, muss sich der Lesegerät des TLVUpdater auf dem Containerelement befinden. Die Methode verwendet 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ückgibt, 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. Anschließend gibt der Updater WEAVE_END_OF_TLV zurück.

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

Details
Parameter
[out] outerContainerType
Ein Verweis auf einen TLVType-Wert, der den Kontext des Updaters empfangen soll.
Rückgabewerte
WEAVE_NO_ERROR
Wenn die Methode erfolgreich war.
WEAVE_ERROR_INCORRECT_STATE
Wenn sich der TLVUpdater-Leser nicht in einem Containerelement befindet.
other
Jeder andere Weave- oder Plattformfehlercode, der von TLVWriter::StartContainer() oder TLVReader::EnterContainer() zurückgegeben wird.

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Schließt das Lesen eines TLV-Containerelements ab 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() müssen Anwendungen einen entsprechenden Aufruf an ExitContainer() senden und den von der Methode EnterContainer() zurückgegebenen Kontextwert übergeben.

Wenn ExitContainer() zurückgegeben wird, wird der TLVUpdater-Leser direkt vor dem ersten Element positioniert, das dem Container in der TLV-Eingabe folgt. Ab diesem Punkt können Anwendungen Next() aufrufen, um alle verbleibenden Elemente zu durchlaufen.

Sobald EnterContainer() aufgerufen wurde, können Anwendungen jederzeit ExitContainer() für den Updater aufrufen, unabhängig davon, ob alle Elemente im zugrunde liegenden Container gelesen wurden. Wenn Sie ExitContainer() aufrufen, bevor alle Elemente im Container gelesen werden, wird der aktualisierte Container in der TLV-Ausgabe abgeschnitten.

Details
Parameter
[in] outerContainerType
Der TLVType-Wert, der von der Methode EnterContainer() zurückgegeben wurde.
Rückgabewerte
WEAVE_NO_ERROR
Wenn die Methode erfolgreich war.
WEAVE_ERROR_TLV_UNDERRUN
Wenn die zugrunde liegende TLV-Codierung vorzeitig beendet wurde.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Der Updater hat einen ungültigen oder nicht unterstützten TLV-Elementtyp festgestellt.
WEAVE_ERROR_INVALID_TLV_TAG
Der Updater hat in einem ungültigen Kontext ein TLV-Tag gefunden.
other
Jeder andere Weave- oder Plattformfehlercode, 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 Eingabepuffer zu bearbeiten.

Beim Aufrufen dieser Methode werden die TLV-Daten im Zwischenspeicher an das Ende des Zwischenspeichers verschoben und ein privates TLVReader-Objekt in diesem verschobenen Zwischenspeicher initialisiert. Außerdem wird im freien Speicherplatz, der jetzt am Anfang zur Verfügung steht, ein privates TLVWriter-Objekt initialisiert. Anwendungen können das Objekt TLVUpdater verwenden, um die TLV-Daten zu parsen und um vorhandene Elemente zu ändern oder zu löschen oder der Codierung neue Elemente hinzuzufügen.

Details
Parameter
[in] buf
Ein Zeiger auf einen Zwischenspeicher, der die zu bearbeitenden TLV-Daten enthält.
[in] dataLen
Die Länge der TLV-Daten im Zwischenspeicher.
[in] maxLen
Die Gesamtlänge des Zwischenspeichers.
Rückgabewerte
WEAVE_NO_ERROR
Wenn die Methode erfolgreich war.
WEAVE_ERROR_INVALID_ARGUMENT
Wenn die Pufferadresse ungültig ist.
WEAVE_ERROR_BUFFER_TOO_SMALL
Wenn der Zwischenspeicher 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 TLV-Daten in dem Zwischenspeicher, auf den 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, und ein neues privates TLVWriter-Objekt wird initialisiert, um in den freigegebenen Zwischenspeicher zu schreiben.

Hinweis: Wenn der TLVReader bereits auf „An“ steht, eines Elements wird zuerst vom Anfang des Elements gesichert. Beachten Sie auch, dass dieses Back-Off gut bei Containerelementen funktioniert. Wenn TLVReader also bereits zum Aufrufen von EnterContainer() verwendet wurde, gibt es nichts für das Backoff. Wenn sich der TLVReader jedoch auf dem Containerelement befand und EnterContainer() noch nicht aufgerufen wurde, wird das Objekt TLVReader am Anfang des Container-Head zurückgeführt.

Das Eingabeobjekt TLVReader wird vor der Rückgabe zerstört und die Anwendung darf bei der Rückgabe nicht dasselbe 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
Wenn die Methode erfolgreich war.
WEAVE_ERROR_INVALID_ARGUMENT
Wenn die Pufferadresse ungültig ist.
WEAVE_ERROR_NOT_IMPLEMENTED
Wenn der Reader in einer Zwischenspeicherkette initialisiert wurde.

Verschieben

WEAVE_ERROR Move(
  void
)

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

Mit der Methode Move() wird das aktuelle Element, auf dem sich der Leser des TLVUpdater befindet, in den Autor des TLVUpdater kopiert. Die Anwendung sollte Next() aufrufen und den Reader des TLVUpdater auf einem Element positionieren, bevor diese Methode aufgerufen wird. Wenn sich der Reader zum Zeitpunkt des Aufrufs in einem Containerelement befindet, werden wie bei der Methode TLVReader::Next() alle Mitglieder des Containers kopiert. Wenn sich der Leser auf keinem Element befindet, ändert sich beim Aufrufen dieser Methode nichts.

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

MoveUntilEnd

void MoveUntilEnd(
  void
)

Verschiebt alles vom aktuellen Lesepunkt des TLVUpdater bis zum Ende des TLV-Zwischenspeichers der Eingabe in die Ausgabe.

Diese Methode unterstützt das Verschieben des gesamten Daten vom aktuellen Lesepunkt des TLVUpdater bis zum Ende des Reader-Zwischenspeichers zum Autor des TLVUpdater.

Weiter

WEAVE_ERROR Next(
  void
)

Das aktuelle Element wird übersprungen und das Objekt TLVUpdater zum nächsten Element in der TLV verschoben.

Die Methode Next() überspringt das aktuelle Element in der TLV-Eingabe und leitet den Reader des TLVUpdater zum nächsten Element weiter, das sich im selben Begrenzungskontext befindet. Wenn sich der Leser auf der äußersten Ebene einer TLV-Codierung befindet, wird er durch das Aufrufen von Next() zum nächsten, obersten Element weitergeleitet. Wenn sich das Lesegerät in einem TLV-Containerelement (einer Struktur, einem Array oder einem Pfad) befindet, wird es durch Aufrufen von Next() zum nächsten Mitgliedselement des Containers weitergeleitet.

Da Next() die Leserbewegung auf den aktuellen Begrenzungskontext beschränkt, wird Next() aufgerufen, wenn sich der Leser auf einem Containerelement befindet, über den Container. Dabei werden seine Mitgliedselemente (und die Mitglieder aller verschachtelten Container) übersprungen, bis das erste Element nach dem Container erreicht wird.

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

Details
Rückgabewerte
WEAVE_NO_ERROR
Ob der TLVUpdater-Leser erfolgreich in einem neuen Element positioniert wurde.
other
Gibt die Weave- oder Plattformfehlercodes zurück, die von den Methoden TLVReader::Skip() und TLVReader::Next() zurückgegeben werden.

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
)

Legen Sie die implizite Profil-ID für das Objekt TLVUpdater 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 mit dem neuen Element verknüpften Tags mit dem Wert von profileId übereinstimmt, codiert der Updater das Tag implizit. Dabei wird die Profil-ID weggelassen.

Details
Parameter
[in] profileId
Die Profil-ID von Tags, die in impliziter Form codiert werden sollen.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)