Englisch version   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

Download

Verwendung

Referenz

Eigenschaften

Funktionen

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. Dir Voreinstellung ist "0x".

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

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.
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.
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.
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.
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.
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.
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.

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:

Werkzeuge

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