The host uses this command to request a file stored on the device. File types include standard files (images and certificates), MagTek custom files (configuration, firmware), and in some cases even large data blob output (such as signature capture data). In many cases, the files retrieved by this command have been sent by a host previously using Start Send File to Device (Secured) - Command 0xD811 or Start Send File to Device (Unsecured) - Command 0xD812. In other cases, such as retrieving signature capture data, the data may originate with the device and the host uses this command to retrieve it. Such data is not persistent, in the sense that the device does not retain it through power cycles.
The sequence of events is as follows:
1
Host composes and sends request
The host composes a command request in the format below and sends it to the device.
2
The device sends a response in the format below so the host knows it can begin listening for a file message.
3
The device sends a Data File Message to the host. If the host does not receive file data within a reasonable period of time, it should time out and stop listening for the data file.
4
Upon receiving the end of the Data File Message, the host should check to make sure the File ID, length, and hash of the File Payload in the Data File Message match the values the device specified in its response to ensure the file has not been tampered with.
Tag
Len
Value / Description
Typ
Req
Default
Tag
Len
Value / Description
Typ
Req
Default
If the request started successfully, the Request Status in the message wrapper is OK, Done.
Example (Hex):
Example (Hex):
D821 = Start Get File from Device - Command 0xD821
81
04
File ID from Table 206
B
R
87
01
Progress indicator behavior (Reserved for future use / Subject to change)
0x00 = None
0x01 = LED
B
O
Null
End of any wrappers, at minimum including Request Message
D821 = Start Get File from Device - Command 0xD821
81
04
File ID from Table 206
B
R
A2
var
File transfer properties
T
R
/81
var
Length of File Payload — This is the length of the File Payload parameter in the Data File Message the device sends to the host.
B
R
/82
01
Hash Checksum Type
0x04 = SHA-256
B
R
/83
20
Hash Checksum
Anticipated checksum calculated against the File Payload, according to the standard specified in Hash Checksum Type.
B
R
A3
var
File Description
The values the host populated for convenience when it sent the file to help identify the file. Not all values are required.
T
R
/81
var
File Description
The values the host populated for convenience when it sent the file to help identify the file. Not all values are required.
B
O
Null
/82
var
File Label
Maximum length 16 bytes Reserved for future use.
B
O
Null
/83
var
File Version
Maximum length 7 bytes Reserved for future use.
B
O
Null
/84
var
File Date
Maximum length 20 bytes Reserved for future use.
B
O
Null
End of any wrappers, at minimum including Response Message
Beginning of any wrappers, at minimum including Request Message
Beginning of any wrappers, at minimum including Response Message
Device acknowledges readiness
Device sends Data File Message
Host validates received file
Table SFGD-1 - Start Get File from Device - Request Data for Command 0xD821
Table SFGD-2 - Start Get File from Device - Response Data for Command 0xD821