This repository was archived by the owner on Aug 31, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 227
Expand file tree
/
Copy pathbinaryDecode.lcdoc
More file actions
121 lines (96 loc) · 5.31 KB
/
binaryDecode.lcdoc
File metadata and controls
121 lines (96 loc) · 5.31 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
Name: binaryDecode
Type: function
Syntax: binaryDecode(<formatsList>, <data>, <variablesList>)
Summary:
Decodes binary data and places it into the specified
<variable|variables>.
Introduced: 1.0
OS: mac, windows, linux, ios, android
Platforms: desktop, server, mobile
Example:
binaryDecode("h","M",theHex) -- converts M to its hex equivalent
Example:
binaryDecode("a*",receivedData,textData) -- converts data to text
Example:
binaryDecode("x12Sh16",picHeader,junk,numColors,colorTable)
Example:
binaryDecode(myFormat,placeHolder,importantStuff)
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
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 (string):
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.
Returns:
The <binaryDecode> <function> <return|returns> the number of dataTypes
that were successfully converted and placed in <variable|variables> (not
counting data skipped by the x dataType). The actual data is placed in
the variables, rather than returned by the function.
Description:
Use the <binaryDecode> function to convert <binary file|binary data>
into a form that can be manipulated by <handler|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 variable|local variables> when you use them.
Although the x dataType skips the specified number of <byte|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 <byte|bytes> than are in the
<data>, the <binaryDecode> <function> ignores the remaining
<byte|bytes>. If the <formatsList> specifies more <byte|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> <return|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
References: put (command), function (control structure),
numToChar (function), format (function), value (function),
return (glossary), binary file (glossary), variable (glossary),
handler (glossary), local variable (glossary), byte (glossary), command (glossary)