English version

Motivation

Bei technischen Anwendungen oder bei der Ansteuerung von Geräten ist es häufig notwendig, mit Binärdaten zu arbeiten. Diese Extension erlaubt es, ein Binärdatenfeld (Byte Array) zu pflegen.

Die UDP-Extension kann bereits mit Byte-Arrays umgehen, Updates zum TCP-Client erfolgen in Kürze.

Versionshistorie

Version	Anpassungen
1.0 (2021-04-02)	Initiale Version
1.1 (2021-05-21)	Fehler bei ReadWord, ReadDWord und ToHex behoben
1.2 (2021-12-13)	Methode ToString benutzte eine Funktion, die erst bei JAVA 8 zur Verfügung steht.
1.3 (2022-05-13)	- Methoden WriteToFile, ReadFromFile und DeleteFile hinzugefügt. - Methoden AddUTF8String, AddASCIIString, ReadUTF8String und ReadASCIIString hinzugefügt. - Methode GetUTF8ByteSize hinzugefügt.
1.4 (2024-03-13)	- Methoden WriteToFileSync, ReadFromFileSync hinzugefügt.

Inhaltsverzeichnis

Beispiel ByteArrayTest

Werkzeuge

Download

Das ZIP-Archiv UrsAI2ByteArray zum Download. Das Archiv enthält den Quellcode, das kompilierte Binary zum Upload in den App Inventor und eine Beispiel-Anwendung.

Verwendung

Die Byte-Array-Extension erlaubt den sequentiellen und und den wahlfreien Zugriff auf die gespeicherten Elemente. Die Index-Basis (der Index der ersten Elements) für wahlfreien Zugriff kann über die Eigenschaft Base festgelegt werden. Es sind die Angaben 1 (wie im App Inventor üblich) oder 0 (wie in Java oder C üblich) möglich.

Die Komponente beginnt mit einem leeren Array, d.h. es enthält keine Elemente. Elemente können über die Methoden AddByte (vorzeichenlose 8-Bit-Zahl [0..255]), AddWord (vorzeichenlose 16-Bit-Zahl [0..65.536]) oder AddDWord (vorzeichenlose 32-Bit-Zahl [0..4.294.967.296]) hinzugefügt werden. Bei AddWord und AddDWord bestimmt die Eigenschaft MsbFirst die Reihenfolge (Byte Order) mit der die Bytes an das Array angefügt werden. Man kann dem Array mit der Methode Append den Inhalt eines anderen Byte-Arrays hinzufügen.

Die Funktion Fill füllt das Array mit einer angegebenen Anzahl Elementen mit einem angegebenen Wert auf. Die Funktion InsertByteAt fügt ein Byte an der angegebenen Position ein. Die anderen Elemente werden dabei um eine Position nach hinten verschoben. RemoveByteAt löscht das Byte an der angegebenenPosition. Die folgenden Bytes werden nach vorn geschoben. Mit der Funktion SetByteAt kann ein Byte abgeändert werden.

Die Funktion Clear löscht alle Elemente aus dem Byte-Array.

Das sequentielle Auslesen geschieht über die Funktionen ReadByte, ReadWord oder ReadDWord. Die Eigenschaft MsbFirst bestimmt auch die Byte-Reihenfolge. Die Eigenschaft ReadIndex bestimmt die Stelle im Array, die als nächstes ausgelesen wird. Um an einer bestimmten Stelle zu lesen, kann ReadIndex auch entsprechend gesetzt werden. Die Eigenschaft Available gibt an, wie viele Bytes noch gelesen werden können.

Die Methode ToString liefert den Inhalt des Arrays als Folge von zweistelligen Hexadezimalzahlen. Mit ToHex kann ein Byte, ein Wort oder ein Doppelwort in seine Hexadezimaldarstellung konvertiert werden. Die Eigenschafft HexPrefix bestimmt, welche Zeichenfolge der Hexadezimalzahl voran gestellt wird. Die Voreinstellung ist "0x".

Mit den Methoden AddUTF8String, AddASCIIString, ReadUTF8String und ReadASCIIString lassen sich Strings einfügen und auslesen. UTF-8 codierte Strings benötigen meist mehr als ein Byte pro Zeichen. GetUTF8ByteSize liefert die Anzahl Bytes, die zur Speicherung eines UTF-8 Strings benötigt werden.

Über die Methoden WriteToFile und ReadFromFile lassen sich Inhalte in eine Datei schreiben oder aus einer Datei auslesen. Werden z.B. Bilder per UDP (URS AI2 UDP Extension) oder MQTT (URS AI2 MQTT Extension) übertragen, lassen diese nicht direkt in eine Image-Komponente einfügen. Hier hilft es, die Daten in einer temporären Zwischendatei abzulegen und von dort in den Image-Block zu laden. Beide Funktionen verrichten ihre Arbeit asynchron! Das Ende einer Datei-Operation und damit die Verfügbarkeit der Datei bzw. der Daten wird über die Ereignisse AfterFileWritten und AfterFileRead angezeigt. AfterFileWritten liefert zusätzlich den absoluten Pfad auf die geschriebene Datei zurück.

Mit den Methoden WriteToFileSync und ReadFromFileSync werden die Daten synchron geschrieben bzw. gelesen. D.h. die Funktionen kehren erst dann zurück, wenn die Operation abgeschlossen ist und die Datei bzw. die Daten verfügbar sind. Bei größeren Datenmengen kann dies zu längeren Anwortzeiten führen.

Mit DeleteFile können (temporäre) Dateien wieder gelöscht werden.

Die Konvention für Dateinamen (Pfade) entspricht der der Standard-File-Komponente.

Referenz

Eigenschaften

Available: Liefert die Anzahl Bytes, die noch sequentiell ausgelesen werden können.
Base: Ruft den Index des ersten Elements ab oder legt in fest. Es sind die Angaben 1 (wie im App Inventor üblich) oder 0 (wie in Java oder C üblich) möglich. Werte größer als 1 werden zu 1 und Werte kleiner als 0 werden zu 0 gewandelt. Die Voreinstellung ist 1.
HexPrefix: Ruft den Vorspann für die Hexadezimaldarstellung (siehe ToString und ToHex) ab oder legt ihn fest. Die Voreinstellung ist "0x".
MsbFirst: Ruft die Reihenfolge ab oder legt sie fest, mit der die Bytes der Funktionen AddWord und AddDWord angefügt bzw. mit ReadWord und ReadDWord ausgelesen werden. Die Voreinstellung ist true.
ReadIndex: Ruft die Position ab, mit der beim sequentiellen Lesen fortgefahren wird, oder legt sie fest. Die Voreinstellung ist der Wert von Base.
Size: Ruft ab, wie viele Bytes im Byte-Array gespeichert sind.
Version: Ruft die Version der Extension ab.

Funktionen

AddASCIIString (Text): Fügt die US-ASCII-Codierung (7 Bit) des angegebenen Strings an das Ende des Byte-Arrays an. Im US-ASCII-Code nicht darstellbare Zeichen werden durch '?' ersetzt.
AddByte (Byte): Fügt ein Byte (vorzeichenlose 8-Bit-Zahl [0..255]) an das Ende des Byte-Arrays an.

Ist die Wertangabe kleiner als 0 oder größer als 255 wird der Wert nicht angefügt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17200 ("Value out of range.") ausgelöst.
AddDWord (DWord): Fügt ein Doppelwort (vorzeichenlose 32-Bit-Zahl [0..4.294.967.296]) an das Ende des Byte-Arrays an. Die Eigenschaft MsbFirst bestimmt die Byte-Reihenfolge.

Ist die Wertangabe kleiner als 0 oder größer als 4.294.967.296 wird der Wert nicht angefügt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17200 ("Value out of range.") ausgelöst.
AddWord (Word): Fügt ein Wort (vorzeichenlose 16-Bit-Zahl [0..65.536]) an das Ende des Byte-Arrays an. Die Eigenschaft MsbFirst bestimmt die Byte-Reihenfolge.

Ist die Wertangabe kleiner als 0 oder größer als 65.536 wird der Wert nicht angefügt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17200 ("Value out of range.") ausgelöst.
AddUTF8String (Text): Fügt die UTF-8-Codierung des angegebenen Strings an das Ende des Byte-Arrays an. UTF-8 codierte Strings benötigen meist mehr als ein Byte pro Zeichen. GetUTF8ByteSize liefert die Anzahl Bytes, die zur Speicherung eines UTF-8 Strings benötigt werden.
Append (Array): Fügt den Inhalt des angegeben Byte-Arrays an. Array muss eine Instanz von der UrsAI2ByteArray-Extension sein.

Ist dies nicht der Fall nicht angefügt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17202 ("Invalid type.") ausgelöst.
Clear (): Entfernt alle Elemente aus dem Byte-Array. Die Eigenschaft ReadIndex wird auf den Wert von Base zurück gesetzt.
DeleteFile (FileName): Löscht die angegebene Datei (siehe File.Delete).
Fill (Count, Value): Füllt das Byte-Array mit Count Bytes und belegt sie mit dem Wert Value. Bereits enthaltene Elemente werden vorher gelöscht (s. Clear). Die Eigenschaft ReadIndex wird auf den Wert von Base zurück gesetzt. Value muss eine vorzeichenlose Zahl im Bereich [0..255]) sein.

Ist Value kleiner als 0 oder größer als 255 wird die Funktion nicht ausgeführt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17200 ("Value out of range.") ausgelöst.
GetByteAt (Index): Ruft den Wert des Elements an der Stelle Index ab.

Ist der Wert von Index kleiner als Base oder zeigt hinter das Array, wird das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17201 ("Index out of range.") ausgelöst und der Wert 0 zurück geliefert.
GetUTF8ByteSize (Text): Liefert die Anzahl Bytes, die zur Speicherung eines UTF-8 Strings benötigt werden. UTF-8 codierte Strings benötigen meist mehr als ein Byte pro Zeichen.
InsertByteAt (Index, Byte): Fügt ein Byte an die angegebene Position Index ein. Folgende Elemente werden nach hinten geschoben. Zeigt ReadIndex hinter die Einfügestelle, wird er ebenfalls verschoben, so dass er auf den selben Wert wie vor der Einfügung weist. Byte muss eine vorzeichenlose Zahl im Bereich [0..255]) sein.

Ist der Wert von Index kleiner als Base oder zeigt hinter das Array, die Funktion nicht ausgeführt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17201 ("Index out of range.") ausgelöst. Ist Byte kleiner als 0 oder größer als 255, wird die Funktion nicht ausgeführt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17200 ("Value out of range.") ausgelöst.
ReadASCIIString (): Liest sequentiell einen US-ASCII (7 Bit) String von der aktuellen Position bis zum Ende.
ReadByte (): Ruft den Wert des Element ab, auf den ReadIndex zeigt. ReadIndex wird inkrementiert.

Steht kein Byte mehr zur Verfügung (s. Available), wird das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17203 ("Read beyond end of array.") ausgelöst und der Wert 0 zurück geliefert.
ReadFromFile (FileName): Fügt den Inhalt der angegebenen Datei an des Ende das Byte-Arrays an (siehe File.ReadFrom). Die Verfügbarkeit der Daten wird durch das Ereignis AfterFileRead angezeigt.
ReadFromFileSync (FileName): Fügt den Inhalt der angegebenen Datei an des Ende das Byte-Arrays an (siehe File.ReadFrom).
ReadDWord (): Ruft das Doppelwort (4 Bytes) ab, auf das ReadIndex zeigt. ReadIndex wird inkrementiert. Die Eigenschaft MsbFirst bestimmt die Byte-Reihenfolge.

Stehen nicht mehr genügend Bytes zur Verfügung (s. Available), wird das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17203 ("Read beyond end of array.") ausgelöst und der Wert 0 zurück geliefert.
ReadUTF8String (): Liest sequentiell einen UTF-8 String von der aktuellen Position bis zum Ende.
ReadWord (): Ruft das Wort (2 Bytes) ab, auf das ReadIndex zeigt. ReadIndex wird inkrementiert. Die Eigenschaft MsbFirst bestimmt die Byte-Reihenfolge.

Stehen nicht mehr genügend Bytes zur Verfügung (s. Available), wird das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17203 ("Read beyond end of array.") ausgelöst und der Wert 0 zurück geliefert.
RemoveByteAt (Index): Entfernt das Byte an der Position Index. Folgende Elemente werden nach vorn geschoben. Zeigt ReadIndex hinter die gelöschte Position, wird er ebenfalls verschoben, so dass er auf den selben Wert wie vor der Einfügung weist.

Ist der Wert von Index kleiner als Base oder zeigt hinter das Array, wird die Funktion nicht ausgeführt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17201 ("Index out of range.") ausgelöst.
SetByteAt (Index, Byte): Ändert das Byte an der Position Index ein. Byte muss eine vorzeichenlose Zahl im Bereich [0..255]) sein.

Ist der Wert von Index kleiner als Base oder zeigt hinter das Array, wird die Funktion nicht ausgeführt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17201 ("Index out of range.") ausgelöst. Ist Byte kleiner als 0 oder größer als 255 wird die Funktion nicht ausgeführt und das Ereignis Screen.ErrorOccurred mit der Fehlernummer 17200 ("Value out of range.") ausgelöst.
ToHex (Value, Digits): Konvertiert eine vorzeichenlose Zahl (8, 16, oder 32 Bit) in die Hexadezimaldarstellung. Der Hexadezimalzahl wird der Wert von HexPrefix voran gestellt. Ist Digits nicht 2, 4 oder 8 oder Value kleiner als 0 oder größer als 4.294.967.295 (0xFFFFFFFF), wird "--" ausgegeben.
ToString (): Liefert den Inhalt des Arrays als Folge von zweistelligen Hexadezimalzahlen. Jeder Hexadezimalzahl wird der Wert von HexPrefix voran gestellt.
WriteToFile (FileName, Append): Schreibt den Inhalt das Byte-Arrays in die angegebene Datei (siehe File.SaveFile). Das Ende des Schreibvorgangs, (die Verfügbarkeit der Datei) wird durch das Ereignis AfterFileWritten angezeigt.
WriteToFileSync (FileName, Append): Schreibt den Inhalt das Byte-Arrays in die angegebene Datei (siehe File.SaveFile).

Ereignisse

AfterFileRead(): Der Lesevorgang ist beendet (siehe ReadFromFile).
AfterFileWritten (FileName, FilePath): Der Schreibvorgang wurde beendet (siehe WriteToFile). FileName: der Name der Datei, FilePath: der absolute Pfad der Datei.

Beispiel ByteArrayTest

Das Beispiel baut ein Byte-Array auf und liest es anschließend aus.

So wird das Byte-Array aufgebaut:

Das wurde wieder ausgelesen:


Einfacher Test bzw. synchrones Lesen und Schreiben.	Asynchrones Lesen und Schreiben.

Werkzeuge

Für die Erstellung eigener Extensions habe ich einige Tipps zusammengestellt: AI2 FAQ: Extensions entwickeln. Auf der Seite findet man noch weitere Hinweise.