Livecode Wiki
Advertisement

Decodes binary data and places it into the specified variables.

Built-in Function handler[]

Syntax:

binaryDecode(<formatsList>, <data>, <variablesList>)

Examples:

binaryDecode("h","M",theHex) -- converts M to its hex equivalent
binaryDecode("a*",receivedData,textData) -- converts data to text
binaryDecode("x12Sh16",picHeader,junk,numColors,colorTable)
binaryDecode(myFormat,placeHolder,importantStuff)

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. See http://perldoc.perl.org/functions/pack.html

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. So you must create them before!

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
  put binaryDecode("i5x2a24xi2", dataToConvert, headerData, placeholder, bodyData, placeholder, footerData) into convertResult
 if convertResult < 3 then return "Error: data was corrupted"
end convertStuff


Parameters:

  • 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
    • amount: 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. 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 (string): A string of encoded binary data.
  • variablesList: A comma-separated list of local or global variable names. The number ofvariable names must be the same as the number of dataTypes specified in the formatsList, and the variables must already exist.
  • Returns: The binaryDecode function returns the number of dataTypes that were successfully converted and placed in variables (notcounting data skipped by the x dataType). The actual data is placed in the variables, rather than returned by the function.

See also: numToChar (function),format (function),value (function),

Advertisement