ae-protocol.md

   1 Overview
   2 ========
   3
   4 The AE protocol works by exchanging messages between the Amiga and the Client (e.g. an IBM PC).
   5
   6 Each message consists of a header and optionally payload data. Both parts carry CRC32 checksums
   7 to ensure data integrity.
   8
   9 Message header
  10 --------------
  11
  12 | Bytes          | Content                      |
  13 | -------------- | ---------------------------- |
  14 | 2              | Msg (see below)              |
  15 | 2              | Payload length               |
  16 | 4              | Sequence                     |
  17 | 4              | CRC32                        |
  18
  19 Payload (if any)
  20 ----------------
  21
  22 | Bytes          | Content                      |
  23 | -------------- | ---------------------------- |
  24 | n              | Payload                      |
  25 | 4              | CRC32                        |
  26
  27 Each message is acknowledged by the receiving side by a 4-Byte "PkOk" response if the checksum matches, "PkRs" otherwise.
  28
  29 Recovery from checksum errors: on "PkRs" non-ack, the sending side re-sends the whole message until "PkOk" is received.
  30 FIXME: is this correct?
  31
  32 Message types
  33 =============
  34
  35 | Msg  | ID                | Sending side | Description                                               |
  36 | ---- | ----------------- | ------------ | --------------------------------------------------------- |
  37 | 0x00 | MSG_NEXT_PART     | Amiga/Client | Ask for next block                                        |
  38 | 0x01 |                   | Amiga/Client | Transfer cancelled                                        |
  39 | 0x02 | MSG_INIT          | Amiga/Client | Initialisation / Init response                            |
  40 | 0x03 | MSG_MPARTH        | Amiga/?      | Multipart header                                          |
  41 | 0x04 | MSG_EOF           | Amiga        | EOF (no payload)                                          |
  42 | 0x05 | MSG_BLOCK         | Amiga        | Next data block                                           |
  43 |      |                   |              |                                                           |
  44 | 0x08 | MSG_EXISTS        | Amiga        | File already exists (when trying to write with 0x66)      |
  45 | 0x09 |                   | Amiga        | Size ? (response to 0x6c)                                 |
  46 | 0x0a | MSG_ACK_CLOSE     | Amiga        | Close response                                            |
  47 | 0x0b |                   | Amiga        | Format response?                                          |
  48 |      |                   |              |                                                           |
  49 | 0x64 | MSG_DIR           | Client       | List directory                                            |
  50 | 0x65 | MSG_FILE_SEND     | Client       | File read                                                 |
  51 | 0x66 | MSG_FILE_RECV     | Client       | File/folder write                                         |
  52 | 0x67 |                   | Client       | File/folder delete (recursively)                          |
  53 | 0x68 |                   | Client       | File rename (name changes) (works on drives, too?)        |
  54 | 0x69 |                   | Client       | File move (path changes)                                  |
  55 | 0x6a |                   | Client       | File copy                                                 |
  56 | 0x6b |                   | Client       | Set attributes and comment                                |
  57 | 0x6c |                   | Client       | Request size on disk (?)                                  |
  58 | 0x6d | MSG_FILE_CLOSE    | Client       | Close file                                                |
  59 | 0x6e |                   | Client       | Format disk (needs Kickstart 2.0 or newer)                |
  60 | 0x6f |                   | Client       | New folder                                                |
  61
  62 Message details
  63 ===============
  64
  65 0x00 MSG_NEXT_PART - Ask for next block
  66 ---------------------------------------
  67
  68 Payload: none
  69
  70 Expected repsonse: MSG_BLOCK or MSG_EOF
  71
  72
  73 0x03 MSG_MPARTH - Multipart header
  74 ----------------------------------
  75
  76 Payload:
  77
  78 | Bytes          | Content                      |
  79 | -------------- | ---------------------------- |
  80 | 4              | length                       |
  81
  82 Expected response: 0x00 MSG_NEXT_PART
  83
  84 0x04 MSG_EOF
  85 ------------
  86
  87 Payload: none
  88
  89 0x05 MSG_BLOCK - Next data block
  90 --------------------------------
  91
  92 Payload:
  93
  94 | Bytes          | Content                      |
  95 | -------------- | ---------------------------- |
  96 | 4              | length n                     |
  97 | n              | data                         |
  98
  99 Expected response: 0x00 MSG_NEXT_PART
 100
 101 0x64 MSG_DIR - List a directory (Client -> Amiga)
 102 -------------------------------------------------
 103
 104 Payload:
 105
 106 | Bytes          | Content                      |
 107 | -------------- | ---------------------------- |
 108 | n              | path                         |
 109 | 1              | 0                            |
 110 | 1              | 1 FIXME ??                   |
 111
 112 Expected response: 0x03 MSG_MPARTH if path exists, MSG_EOF otherwise
 113
 114 Multipart data will be polled in chunks using MSG_NEXT_PART. This data is structured as follows:
 115
 116 | Bytes          | Content                      |
 117 | -------------- | ---------------------------- |
 118 | 4              | number of entries            |
 119 | n              | dir entries                  |
 120
 121 Each dir entry is structured as follows:
 122
 123 | Bytes          | Content                      |
 124 | -------------- | ---------------------------- |
 125 | 4              | len (29+n+m)                 |
 126 | 4              | size                         |
 127 | 4              | used                         |
 128 | 2              | type (0: file, 0x8000: dir)  |
 129 | 2              | attributes                   |
 130 |                |   S: 0x40                    |
 131 |                |   P: 0x20                    |
 132 |                |   A: 0x10                    |
 133 |                |   R: 0x08                    |
 134 |                |   W: 0x04                    |
 135 |                |   E: 0x02                    |
 136 |                |   D: 0x01                    |
 137 | 4              | date                         |
 138 | 4              | time                         |
 139 | 4              | ctime                        |
 140 | 1              | type2 FIXME: ???             |
 141 | n              | name\0                       |
 142 | m              | comment\0                    |
 143
 144
 145 0x65 MSG_FILE_SEND - Read a file
 146 --------------------------------
 147
 148 Payload: filename\0
 149
 150 Expected response: 0x08 MSG_EXISTS if file cannot be opened, 0x03 MSG_MPARTH otherwise
 151
 152
 153 0x66 MSG_FILE_RECV - Write a file (Client -> Amiga)
 154 ---------------------------------------------------
 155
 156 Payload:
 157
 158 | Bytes          | Content                      |
 159 | -------------- | ---------------------------- |
 160 | 4              | header size                  |
 161 | 4              | file size                    |
 162 | 4              | FIXME ??                     |
 163 | 4              | Attributes FIXME: encoding ? |
 164 | 4              | date (hours since 1/1/78)    |
 165 | 4              | time (mins since midnight)   |
 166 | 4              | ctime                        |
 167 | 1              | file type FIXME: encoding?   |
 168 | header_size-29 | file name                    |
 169
 170 Expected response: 0x00 MSG_NEXT_PART if file does not exist (yet), 0x08 MSG_EXISTS otherwise
 171
 172
 173 67 - Delete file/folder
 174 ------------------------
 175
 176 Payload:
 177
 178      Bytes | Content
 179     -------|--------------------
 180          n | Path
 181          1 | 0x00
 182
 183 Then, read type 0 for confirmation.
 184 Then, sendClose() (0xa response: 5x 00).
 185
 186 If Path is a folder, it will be deleted together with its contents.
 187
 188
 189 68 - Rename file/folder
 190 ------------------------
 191
 192 Payload:
 193
 194      Bytes | Content
 195     -------|--------------------
 196          n | Path (including old file name)
 197          1 | 0x00
 198          n | New file name (without path)
 199          1 | 0x00
 200
 201 Then, read type 0 for confirmation.
 202 Then, sendClose() (0xa response: 5x 00).
 203
 204
 205 69 - Move file/folder
 206 ----------------------
 207
 208 Payload:
 209
 210      Bytes | Content
 211     -------|--------------------
 212          n | Path (including old file name)
 213          1 | 0x00
 214          n | New path to contain file (folder without trailing slash or file name)
 215          1 | 0x00
 216          1 | 0xc9 (?)
 217
 218 Then, read type 0 for confirmation.
 219 Then, sendClose() (0xa response: 5x 00).
 220
 221 If Path is a folder, it will be moved together with its contents.
 222 This command appears to work across devices.
 223
 224
 225 6a - Copy file/folder
 226 ----------------------
 227
 228 Payload:
 229
 230      Bytes | Content
 231     -------|--------------------
 232          n | Path (including old file name)
 233          1 | 0x00
 234          n | New path to contain file (folder without trailing slash or file name)
 235          1 | 0x00
 236          1 | 0xc9 (?)
 237
 238 Then, read type 0 for confirmation.
 239 Then, sendClose() (0xa response: 5x 00).
 240
 241 If Path is a folder, it will be moved together with its contents.
 242 This command appears to work across devices.
 243
 244
 245 6b - Set attributes and comment
 246 --------------------------------
 247
 248 Payload:
 249
 250      Bytes | Content
 251     -------|--------------------
 252          4 | Attributes
 253          n | Path
 254          1 | 0x00
 255          n | Comment
 256          1 | 0x00
 257          4 | Checksum? (seems to be 0x00000000 if comment empty)
 258
 259 Then, read type 0 for confirmation.
 260 Then, sendClose() (0xa response: 5x 00).
 261
 262
 263 6c - Request size on disk (?)
 264 ------------------------------------
 265
 266 Payload:
 267
 268      Bytes | Content
 269     -------|--------------------
 270          n | Path
 271          1 | 0x00
 272
 273 Then, read type 0 for confirmation.
 274 Then, read type 9 for 12 bytes of payload (### TODO ###).
 275 Then, send type 0 to request more data (no payload).
 276 Then, read type 9 for 12 bytes of payload (### TODO ###).
 277 Then, send type 0 to request more data (no payload).
 278 Then, read type 0 signaling end of attributes (no payload).
 279 Then, sendClose() (0xa response: 5x 00).
 280
 281 OR
 282
 283 Then, read type 0 for confirmation.
 284 Then, read type 0 signaling end of attributes (no payload).
 285 Then, sendClose() (0xa response: 5x 00).
 286
 287
 288
 289 6d - Close file
 290 ----------------
 291
 292 No payload.
 293
 294 Then, read type 0x0a for confirmation (typical payload: 5 bytes of 0x00).
 295
 296 This is used to finish an operation, such as a directory listing
 297 or renaming a file.
 298
 299
 300 6e - Format disk
 301 -----------------
 302
 303 ### TODO ###
 304
 305
 306 6f - New folder
 307 ----------------
 308
 309 Payload:
 310
 311      Bytes |  Content
 312     -------|--------------------
 313          n | Parent path
 314          1 | 0x00
 315
 316 Then, read type 0 for confirmation.
 317 Then, sendClose() (0xa response: 5x 00).
 318
 319 The host will create a new folder in the given path, together with a
 320 matching .info file.
 321 The folder name cannot be chosen, and will be something like "Unnamed1".
 322
 323 To create a folder with a specific name, use 0x66.
 324 Note that 0x66'ing a folder does not seem to set its time.