binaryDecode |
Type | function |
Dictionary | LCS |
Library | LiveCode Script |
Syntax | binaryDecode(<formatsList>, <data>, <variablesList>)
|
Summary | Decodes binary data and places it into the specified
variables.
|
Introduced | 1.0 |
OS | mac, windows, linux, ios, android |
Platforms | desktop, server, mobile |
Parameters | Name | Type | Description |
---|
formatsList | | The formatsList consists of one or more dataTypes, each followed
optionally by an amount. A dataType is one of the following single letters:
- x: skip next amount bytes of data
- a: convert next amount bytes of data to characters
- A: convert next amount bytes of data (skipping spaces) to characters
- b: convert next amount bits of data to 1s and 0s
- B: convert next amount bits of data to 1s and 0s, starting at the high end of each byte
- h: convert next amount bytes of data to hexadecimal digits
- H: convert next amount bytes of data to hexadecimal digits, starting at the high end of each byte
- c: convert next amount bytes of data to signed 1-byte integers
- C: convert next amount bytes of data to unsigned 1-byte integers
- s: convert next amount 2-byte chunks of data to signed integers in host byte order
- S: convert next amount 2-byte chunks of data to unsigned integers in host byte order
- i: convert next amount 4-byte chunks of data to signed integers in host byte order
- I: convert next amount 4-byte chunks of data to unsigned integers in host byte order
- n: convert next amount 2-byte chunks of data to signed integers in network byte order
- N: convert next amount 4-byte chunks of data to signed integers in network byte order
- m: convert next amount 2-byte chunks of data to unsigned integers in network byte order
- M: convert next amount 4-byte chunks of data to unsigned integers in network byte order
- f: convert next amount 4-byte chunks of data to a single-precision float
- d: convert next amount 8-byte chunks of data to a double-precision float
The amount corresponding to each dataType is an integer or
the * character. If no amount is specified, the dataType is
used for a single byte of data. The * character causes the rest of the
data to be converted according to the formatType, so it should appear
only as the last character in the formatsList.
*Important:* If you specify an amount with a string dataType (a or A),
the binaryDecode function places amount bytes in the next variable of the
variablesList. If you specify an amount with a numeric dataType, the function
places amount chunks of data in the next amount variables of the variablesList.
For example, the dataType "a3" requires only one variable, which will
hold a 3-characterstring, but the dataType "h3" requires three
variables, each of which will hold a single hex digit.
|
data | | A string of encoded binary data.
|
variablesList | | A comma-separated list of local or global variable names. The number of
variable names must be the same as the number of dataTypes specified in
the formatsList, and the variables must already exist.
|
|
Example | binaryDecode("h","M",theHex)
binaryDecode("a*",receivedData,textData)
binaryDecode("x12Sh16",picHeader,junk,numColors,colorTable)
binaryDecode(myFormat,placeHolder,importantStuff)
|
Values | Name | Type | Description |
---|
return | | The binaryDecode function returns the number of dataTypes
that were successfully converted and placed in variables (not
counting data skipped by the x dataType). The actual data is placed in
the variables, rather than returned by the function.
|
|
Related | Command: put
Function: numToChar, format, value
Control Structure: function
Glossary: return, binary file, variable, handler, local variable, byte, command
|
Description | Use the binaryDecode function to convert binary data
into a form that can be manipulated by handlers.
The binary data format used by binaryDecode is similar to the format
produced by the "pack" function of the Perl programming language.
You must declare or otherwise create all variables in the
variablesList before using them in the binaryDecode function.
Unlike the put command, the binaryDecode function does not
automatically create local variables when you use them.
Although the x dataType skips the specified number of bytes
rather than converting them, you still must provide a variable for
instances of x that appear in the formatsList. The binaryDecode
function does not change the value of a variable used for the
dataType x.
If the formatsList specifies fewer bytes than are in the
data, the binaryDecode function ignores the remaining
bytes. If the formatsList specifies more bytes than are
in the data, the binaryDecode function converts as many of the
dataTypes as there is data for. Check the value that the
binaryDecode function returns to determine how much data
was actually converted. Here is an example:
on convertStuff dataToConvert
global headerData,placeholder,bodyData,footerData
local convertResult
put binaryDecode("i5x2a24xi2",dataToConvert, \
headerData,placeholder,bodyData,placeholder, \
footerData) into convertResult
if convertResult < 3 then return "Error: data was corrupted"
end convertStuff
|