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 Expected response: 0x6d MSG_FILE_CLOSE
  90
  91 0x05 MSG_BLOCK - Next data block
  92 --------------------------------
  93
  94 Payload:
  95
  96 | Bytes          | Content                      |
  97 | -------------- | ---------------------------- |
  98 | 4              | offset                       |
  99 | n              | data                         |
 100
 101 Expected response: 0x00 MSG_NEXT_PART
 102
 103 0x64 MSG_DIR - List a directory (Client -> Amiga)
 104 -------------------------------------------------
 105
 106 Payload:
 107
 108 | Bytes          | Content                      |
 109 | -------------- | ---------------------------- |
 110 | n              | path                         |
 111 | 1              | 0                            |
 112 | 1              | 1 FIXME ??                   |
 113
 114 Expected response: 0x03 MSG_MPARTH if path exists, MSG_EOF otherwise
 115
 116 Multipart data will be polled in chunks using MSG_NEXT_PART. This data is structured as follows:
 117
 118 | Bytes          | Content                      |
 119 | -------------- | ---------------------------- |
 120 | 4              | number of entries            |
 121 | n              | dir entries                  |
 122
 123 Each dir entry is structured as follows:
 124
 125 | Bytes          | Content                      |
 126 | -------------- | ---------------------------- |
 127 | 4              | len (29+n+m)                 |
 128 | 4              | size                         |
 129 | 4              | used                         |
 130 | 2              | type (0: file, 0x8000: dir)  |
 131 | 2              | attributes                   |
 132 |                |   S: 0x40                    |
 133 |                |   P: 0x20                    |
 134 |                |   A: 0x10                    |
 135 |                |   R: 0x08                    |
 136 |                |   W: 0x04                    |
 137 |                |   E: 0x02                    |
 138 |                |   D: 0x01                    |
 139 | 4              | date                         |
 140 | 4              | time                         |
 141 | 4              | ctime                        |
 142 | 1              | type2 FIXME: ???             |
 143 | n              | name\0                       |
 144 | m              | comment\0                    |
 145
 146
 147 0x65 MSG_FILE_SEND - Read a file
 148 --------------------------------
 149
 150 Payload: filename\0
 151
 152 Expected response: 0x08 MSG_EXISTS if file cannot be opened, 0x03 MSG_MPARTH otherwise
 153
 154
 155 0x66 MSG_FILE_RECV - Write a file (Client -> Amiga)
 156 ---------------------------------------------------
 157
 158 Payload:
 159
 160 | Bytes          | Content                      |
 161 | -------------- | ---------------------------- |
 162 | 4              | header size                  |
 163 | 4              | file size                    |
 164 | 4              | FIXME ??                     |
 165 | 4              | attributes                   |
 166 |                |   S: 0x40                    |
 167 |                |   P: 0x20                    |
 168 |                |   A: 0x10                    |
 169 |                |   R: 0x08                    |
 170 |                |   W: 0x04                    |
 171 |                |   E: 0x02                    |
 172 |                |   D: 0x01                    |
 173 | 4              | date (hours since 1/1/78)    |
 174 | 4              | time (mins since midnight)   |
 175 | 4              | ctime                        |
 176 | 1              | file type FIXME: encoding?   |
 177 | header_size-29 | file name                    |
 178
 179 Expected response: 0x00 MSG_NEXT_PART if file does not exist (yet), 0x08 MSG_EXISTS otherwise
 180
 181
 182 67 - Delete file/folder
 183 ------------------------
 184
 185 Payload:
 186
 187      Bytes | Content
 188     -------|--------------------
 189          n | Path
 190          1 | 0x00
 191
 192 Then, read type 0 for confirmation.
 193 Then, sendClose() (0xa response: 5x 00).
 194
 195 If Path is a folder, it will be deleted together with its contents.
 196
 197
 198 68 - Rename file/folder
 199 ------------------------
 200
 201 Payload:
 202
 203      Bytes | Content
 204     -------|--------------------
 205          n | Path (including old file name)
 206          1 | 0x00
 207          n | New file name (without path)
 208          1 | 0x00
 209
 210 Then, read type 0 for confirmation.
 211 Then, sendClose() (0xa response: 5x 00).
 212
 213
 214 69 - Move file/folder
 215 ----------------------
 216
 217 Payload:
 218
 219      Bytes | Content
 220     -------|--------------------
 221          n | Path (including old file name)
 222          1 | 0x00
 223          n | New path to contain file (folder without trailing slash or file name)
 224          1 | 0x00
 225          1 | 0xc9 (?)
 226
 227 Then, read type 0 for confirmation.
 228 Then, sendClose() (0xa response: 5x 00).
 229
 230 If Path is a folder, it will be moved together with its contents.
 231 This command appears to work across devices.
 232
 233
 234 6a - Copy file/folder
 235 ----------------------
 236
 237 Payload:
 238
 239      Bytes | Content
 240     -------|--------------------
 241          n | Path (including old file name)
 242          1 | 0x00
 243          n | New path to contain file (folder without trailing slash or file name)
 244          1 | 0x00
 245          1 | 0xc9 (?)
 246
 247 Then, read type 0 for confirmation.
 248 Then, sendClose() (0xa response: 5x 00).
 249
 250 If Path is a folder, it will be moved together with its contents.
 251 This command appears to work across devices.
 252
 253
 254 6b - Set attributes and comment
 255 --------------------------------
 256
 257 Payload:
 258
 259      Bytes | Content
 260     -------|--------------------
 261          4 | Attributes
 262          n | Path
 263          1 | 0x00
 264          n | Comment
 265          1 | 0x00
 266          4 | Checksum? (seems to be 0x00000000 if comment empty)
 267
 268 Then, read type 0 for confirmation.
 269 Then, sendClose() (0xa response: 5x 00).
 270
 271
 272 6c - Request size on disk (?)
 273 ------------------------------------
 274
 275 Payload:
 276
 277      Bytes | Content
 278     -------|--------------------
 279          n | Path
 280          1 | 0x00
 281
 282 Then, read type 0 for confirmation.
 283 Then, read type 9 for 12 bytes of payload (### TODO ###).
 284 Then, send type 0 to request more data (no payload).
 285 Then, read type 9 for 12 bytes of payload (### TODO ###).
 286 Then, send type 0 to request more data (no payload).
 287 Then, read type 0 signaling end of attributes (no payload).
 288 Then, sendClose() (0xa response: 5x 00).
 289
 290 OR
 291
 292 Then, read type 0 for confirmation.
 293 Then, read type 0 signaling end of attributes (no payload).
 294 Then, sendClose() (0xa response: 5x 00).
 295
 296
 297
 298 6d - Close file
 299 ----------------
 300
 301 No payload.
 302
 303 Then, read type 0x0a for confirmation (typical payload: 5 bytes of 0x00).
 304
 305 This is used to finish an operation, such as a directory listing
 306 or renaming a file.
 307
 308
 309 6e - Format disk
 310 -----------------
 311
 312 ### TODO ###
 313
 314
 315 6f - New folder
 316 ----------------
 317
 318 Payload:
 319
 320      Bytes |  Content
 321     -------|--------------------
 322          n | Parent path
 323          1 | 0x00
 324
 325 Then, read type 0 for confirmation.
 326 Then, sendClose() (0xa response: 5x 00).
 327
 328 The host will create a new folder in the given path, together with a
 329 matching .info file.
 330 The folder name cannot be chosen, and will be something like "Unnamed1".
 331
 332 To create a folder with a specific name, use 0x66.
 333 Note that 0x66'ing a folder does not seem to set its time.