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:
Tools
For developing own extensions I gathered some tips: AI2 FAQ: Develop Extensions. On the site you can find further informations.