Deutsche Version
Motivation
In technical applications or when controlling devices, it is often necessary to work with binary
data. This extension allows to maintain a binary data field (byte array).
The UDP extension can already handle byte
arrays, updates to the TCP client will follow shortly.
Version history
Version |
Adjustments |
1.0 (2021-04-02) |
Initial version |
1.1 (2021-05-21) |
Bug fixing at ReadWord, ReadDWord
and ToHex |
1.2 (2021-12-13) |
Method ToString called a function from JAVA 8. |
1.3 (2022-05-13) |
- Methods WriteToFile, ReadFromFile
and DeleteFile added. - Methods
AddUTF8String, AddASCIIString,
ReadUTF8String and ReadASCIIString
added. - Method GetUTF8ByteSize added. |
1.4 (2024-03-13) |
- Methods WriteToFileSync,
ReadFromFileSync added. |
Download
The
UrsAI2ByteArray ZIP
archive for download. The archive contains the source code, the compiled binary for uploading to
the App Inventor and a sample application.
Usage
The byte array extension allows sequential and random access to the stored data. The index base
(the index of the first element) for random access can be set using the
Base property. The values 1 (as usual in App
Inventor) or 0 (as usual in Java or C) are possible.
The component starts with an empty array, which means that it does not contain any elements. Elements
can be added using the methods AddByte (unsigned
8-bit number [0..255]), AddWord (unsigned
16-bit number [0..65.536]) or AddDWord
(unsigned 32-bit number [0..4.294.967.296]). With AddWord and
AddDWord, the property
MsbFirst defines the order (byte
order) with which the bytes are added to the array. You can add the content of another byte array
to the array using the Append method.
The Fill function fills the array with a
specified number of elements with a specified value. The
InsertByteAt function inserts a byte at the specified position.
The other elements are moved back one position.
RemoveByteAt deletes the byte at the specified position. The following
bytes are shifted forward. A byte can be changed with the
SetByteAt function.
The Clear function removes all elements
from the byte array.
The sequential access is done using the ReadByte,
ReadWord or
ReadDWord functions. The
MsbFirst property defines the byte order. The
ReadIndex property specifies the position
in the array that will be read next. In order to read at a certain element,
ReadIndex can also be set accordingly. The
Available property returns how many bytes
can still be read.
The ToString method returns the content
of the array as a sequence of two-digit hexadecimal numbers. With
ToHex a byte, a word or a double word can be converted to its hexadecimal
representation. The HexPrefix property
specifies which character string is placed in front of the hexadecimal number. The default setting
is "0x".
Strings can be inserted and read using the
AddUTF8String,
AddASCIIString,
ReadUTF8String and
ReadASCIIString methods. UTF-8 encoded strings usually require
more than one byte per character. GetUTF8ByteSize
returns the number of bytes required to store a UTF-8 string.
Content can be written to or read from a file using the
WriteToFile and
ReadFromFile methods. For example, if images are transferred via
UDP (URS AI2 UDP Extension)
or MQTT (URS
AI2 MQTT Extension), they cannot be inserted directly into an image component. Here it helps to store the data in
a temporary intermediate file and load it from there into the image block. Both function do
there job asynchronously! The end of a file operation and therefore the availability of the file or data is indicated by the
AfterFileWritten and
AfterFileRead events.
AfterFileWritten returns the absolute path to the written
file.
The WriteToFileSync and
ReadFromFileSync methods are used to write or read
the data synchronously. This means that the functions return when the operation has completed and
the file or data is available. This can lead to longer response times for large amounts of data.
(Temporary) files can be deleted with DeleteFile.
The convention for file names (paths) corresponds to that of the
standard
file component.
Reference
Properties
- Available
-
Returns the number of bytes
that can still be read sequentially.
- Base
- Gets or sets the index of the first item. The entries 1 (as usual in App Inventor) or 0 (as
usual in Java or C) are possible. Values greater than 1 are converted 1 and values less than
0 are converted to 0. The default is 1
- HexPrefix
- Gets or sets the prefix for the hexadecimal representation (see
ToString and ToHex).
The default setting is "0x".
- MsbFirst
- Gets or sets the order in which the bytes of the
AddWord and AddDWord
functions are added or read with ReadWord
and ReadDWord. The default is true.
- ReadIndex
- Gets or sets the position from which to continue reading sequentially. The default is the
value of Base.
- Size
- Getsthe number of stored bytes.
- Version
- Gets the version of the extension.
Methods
- AddASCIIString (Text)
- Appends the US-ASCII (7-bit) encoding of the specified string to the end of the byte array.
Characters that cannot be represented in US-ASCII code are substituted by '?'.
- AddByte (Byte)
- Adds a byte (unsigned 8-bit number [0..255]) to the end of the byte array.
If the specified
value is less than 0 or greater than 255, the value is not added and the
Screen.ErrorOccurred event is triggered with the error number 17200 ("Value out of
range.").
- AddDWord (DWord)
- Adds a double word (unsigned 32-bit number [0..4.294.967.296]) to the end of the byte array.
The MsbFirst property defines the byte
order.
If the specified value is less than 0 or greater than 4,294,967,296, the value is
not added and the
Screen.ErrorOccurred event is triggered with the error number 17200 ("Value out of
range.").
- AddWord (Word)
- Adds a word (unsigned 16-bit number [0..65,536]) to the end of the byte array. The
MsbFirst property defines the byte order.
If the specified value is less than 0 or greater than 65,536, the value is not added and the
Screen.ErrorOccurred event is triggered with error number 17200 ("Value out of range.").
- AddUTF8String (Text)
- Appends the UTF-8 encoding of the specified string to the end of the byte array. UTF-8 encoded
strings usually require more than one byte per character.
GetUTF8ByteSize returns the number of bytes required to
store a UTF-8 string.
- Append (Array)
- Adds the content of the specified byte array. Array must
be an instance of the UrsAI2ByteArray extension.
If this
is not the case, it is not added and the
Screen.ErrorOccurred event is triggered with the error number 17202 ("Invalid type.").
- Clear ()
- Removes all elements from the byte array. The
ReadIndex property is reset to the value of
Base.
- DeleteFile (FileName)
- Deletes the specified file (see
File.Delete).
- Fill (Count, Value)
- Fills the byte array with count bytes and assigns the value Value.
Elements already contained are deleted beforehand (see
Clear). The ReadIndex
property is reset to the value of Base.
Value must be an unsigned number in the range [0..255]).
If Value is less than 0 or greater than 255, the function
is not executed and the
creen.ErrorOccurred event is triggered with error number 17200 ("Value out of range.").
- GetByteAt (Index)
- Gets the value of the item at the position Index.
If the value of Index is less than
Base or points behind the array, the
creen.ErrorOccurred event is triggered with the error number 17201 ("Index out of range.")
and the value 0 is returned.
- GetUTF8ByteSize (Text)
- Returns the number of bytes required to store a UTF-8 string. UTF-8 encoded strings usually
require more than one byte per character.
- InsertByteAt (Index,
Byte)
- Inserts a byte at the position specified Index. The following
elements are pushed back. If ReadIndex
points behind the insertion point, it is also moved so that it points to the same value as before
the insertion.
If the value of Index is less than Base
or Base behind the array, the function is
not executed and the
Screen.ErrorOccurred event is triggered with the error number 17201 ("Index out of
range."). Byte must be an unsigned number in the range [0..255]). If the specified value is less
than 0 or greater than 255, the element will not be replaced and the
Screen.ErrorOccurred event triggered with the error number 17200 ("Value out of range.").
- ReadASCIIString ()
- Reads sequentially a US-ASCII (7 bits) string from the current position to the end.
- ReadByte ()
- Gets the value of the element pointed to by the
ReadIndex. ReadIndex is incremented.
If no more byte is available (see Available),
the
Screen.ErrorOccurred event is triggered with the error number 17203 ("Read beyond end
of array.") and the value 0 is returned.
- ReadDWord ()
- Gets the double word (4 bytes) pointed to by the
ReadIndex. The
MsbFirst property defines the byte order. ReadIndex
is incremented.
If there are not enough bytes available (see
Available), the
Screen.ErrorOccurred event is triggered with the error number 17203 ("Read beyond end
of array.") and the value 0 is returned.
- ReadFromFile (FileName)
- Appends the contents of the specified file to the end of the byte array (see
File.ReadFrom). The availability of the data is indicated by the
AfterFileRead event.
- ReadFromFileSync (FileName)
- Appends the contents of the specified file to the end of the byte array (see
File.ReadFrom). The function returns when the file has been read completely.
- ReadUTF8String ()
- Reads sequentially a UTF8 string from the current position to the end.
- ReadWord ()
- Gets the word (2 bytes) pointed to by the
ReadIndex. The MsbFirst property
defines the byte order. ReadIndex is incremented.
If
there are not enough bytes available (see Available),
the
Screen.ErrorOccurred event is triggered with the error number 17203 ("Read beyond end
of array.") and the value 0 is returned.
- RemoveByteAt (Index)
- Removes the byte at the index position. The following elements are pushed forward. If
ReadIndex points behind the deleted
position, it is also moved so that it points to the same value as before the insertion.
If the value of Index is less than Base or points behind the array, the function is not executed
and the
Screen.ErrorOccurred event is triggered with the error number 17201 ("Index out of
range.").
- SetByteAt (Index,
Byte)
- Changes the byte at the position Index. Byte must be an
unsigned number in the range [0..255]).
If the value of Index is less than Base or points
behind the array, the function is not executed and the
Screen.ErrorOccurred event is triggered with the error number 17201 ("Index out of
range."). If the value of Byte is less than 0 or greater
than 255, the function is not executed and the
Screen.ErrorOccurred event is triggered with error number 17200 ("Value out of range.").
- 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 ist Value kleiner als 0 oder größer als 4.294.967.295
(0xFFFFFFFF), wird "--" ausgegeben.
Converts an unsigned number (8, 16, or 32 bits) to
hexadecimal representation. The hexadecimal number is preceded by the value of
HexPrefix. If
Digits is not 2, 4 or 8 or if Value
is less than 0 or greater than 4,294,967,295 (0xFFFFFFFF), "-" is returned.
- ToString ()
- Returns the content of the array as a sequence of two-digit hexadecimal numbers. Each hexadecimal
number is preceded by the value of HexPrefix.
- WriteToFile (FileName,
Append)
- Writes the contents of the byte array to the specified file (see
File.SaveFile).
The end of the writing process is indicated by the AfterFileWritten event.
- WriteToFileSync (FileName,
Append)
- Writes the contents of the byte array to the specified file (see
File.SaveFile). The function returns when the file has been completely written.
Events
- AfterFileRead()
- The reading process is finished (see ReadFromFile).
- AfterFileWritten (FileName, FilePath)
- The writing process has ended (see WriteToFile).
FileName: the name of the file, FilePath:
the absolute path of the file.
Example ByteArraTest
|
|
The example creates a byte array and then reads it out.
|
This is how the byte array is constructed:
That was read out again:
For developing own extensions I gathered some tips:
AI2 FAQ: Develop Extensions.
On the site you can find further informations.