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.
  28
  29 FIXME: Reply if checksum doesn''t match? Re-sync/recovery?
  30
  31 Message types
  32 =============
  33
  34 | Msg  | ID                | Sending side | Description                                               |
  35 | ---- | ----------------- | ------------ | --------------------------------------------------------- |
  36 | 0x00 | MSG_NEXT_PART     | Amiga/Client | Ask for next block                                        |
  37 | 0x01 |                   | Amiga/Client | Transfer cancelled                                        |
  38 | 0x02 | MSG_INIT          | Amiga/Client | Initialisation / Init response                            |
  39 | 0x03 | MSG_MPARTH        | Amiga/?      | Multipart header                                          |
  40 | 0x04 | MSG_EOF           | Amiga        | EOF (no payload)                                          |
  41 | 0x05 | MSG_BLOCK         | Amiga        | Next data block                                           |
  42 |      |                   |              |                                                           |
  43 | 0x08 | MSG_EXISTS        | Amiga        | File already exists (when trying to write with 0x66)      |
  44 | 0x09 |                   | Amiga        | Size ? (response to 0x6c)                                 |
  45 | 0x0a | MSG_ACK_CLOSE     | Amiga        | Close response                                            |
  46 | 0x0b |                   | Amiga        | Format response?                                          |
  47 |      |                   |              |                                                           |
  48 | 0x64 |                   | Client       | List directory                                            |
  49 | 0x65 | MSG_FILE_SEND     | Client       | File read                                                 |
  50 | 0x66 | MSG_FILE_RECV     | Client       | File/folder write                                         |
  51 | 0x67 |                   | Client       | File/folder delete (recursively)                          |
  52 | 0x68 |                   | Client       | File rename (name changes) (works on drives, too?)        |
  53 | 0x69 |                   | Client       | File move (path changes)                                  |
  54 | 0x6a |                   | Client       | File copy                                                 |
  55 | 0x6b |                   | Client       | Set attributes and comment                                |
  56 | 0x6c |                   | Client       | Request size on disk (?)                                  |
  57 | 0x6d | MSG_FILE_CLOSE    | Client       | Close file                                                |
  58 | 0x6e |                   | Client       | Format disk (needs Kickstart 2.0 or newer)                |
  59 | 0x6f |                   | Client       | New folder                                                |
  60
  61 Message details
  62 ===============
  63
  64 64 - List a directory
  65 ----------------------
  66
  67 ### TODO ###
  68
  69
  70 65 - Read a file
  71 -----------------
  72
  73 ### TODO ###
  74
  75
  76 0x66 MSG_FILE_RECV - Write a file (Client -> Amiga)
  77 ---------------------------------------------------
  78
  79 Payload:
  80
  81 | Bytes          | Content                      |
  82 | -------------- | ---------------------------- |
  83 | 4              | header size                  |
  84 | 4              | file size                    |
  85 | 4              | FIXME ??                     |
  86 | 4              | Attributes FIXME: encoding ? |
  87 | 4              | date (hours since 1/1/78)    |
  88 | 4              | time (mins since midnight)   |
  89 | 4              | ctime                        |
  90 | 1              | file type FIXME: encoding?   |
  91 | header_size-29 | file name                    |
  92
  93 Expected response: 0x00 MSG_NEXT_PART if file does not exist (yet), 0x08 MSG_EXISTS otherwise
  94
  95
  96 67 - Delete file/folder
  97 ------------------------
  98
  99 Payload:
 100
 101      Bytes | Content
 102     -------|--------------------
 103          n | Path
 104          1 | 0x00
 105
 106 Then, read type 0 for confirmation.
 107 Then, sendClose() (0xa response: 5x 00).
 108
 109 If Path is a folder, it will be deleted together with its contents.
 110
 111
 112 68 - Rename file/folder
 113 ------------------------
 114
 115 Payload:
 116
 117      Bytes | Content
 118     -------|--------------------
 119          n | Path (including old file name)
 120          1 | 0x00
 121          n | New file name (without path)
 122          1 | 0x00
 123
 124 Then, read type 0 for confirmation.
 125 Then, sendClose() (0xa response: 5x 00).
 126
 127
 128 69 - Move file/folder
 129 ----------------------
 130
 131 Payload:
 132
 133      Bytes | Content
 134     -------|--------------------
 135          n | Path (including old file name)
 136          1 | 0x00
 137          n | New path to contain file (folder without trailing slash or file name)
 138          1 | 0x00
 139          1 | 0xc9 (?)
 140
 141 Then, read type 0 for confirmation.
 142 Then, sendClose() (0xa response: 5x 00).
 143
 144 If Path is a folder, it will be moved together with its contents.
 145 This command appears to work across devices.
 146
 147
 148 6a - Copy file/folder
 149 ----------------------
 150
 151 Payload:
 152
 153      Bytes | Content
 154     -------|--------------------
 155          n | Path (including old file name)
 156          1 | 0x00
 157          n | New path to contain file (folder without trailing slash or file name)
 158          1 | 0x00
 159          1 | 0xc9 (?)
 160
 161 Then, read type 0 for confirmation.
 162 Then, sendClose() (0xa response: 5x 00).
 163
 164 If Path is a folder, it will be moved together with its contents.
 165 This command appears to work across devices.
 166
 167
 168 6b - Set attributes and comment
 169 --------------------------------
 170
 171 Payload:
 172
 173      Bytes | Content
 174     -------|--------------------
 175          4 | Attributes
 176          n | Path
 177          1 | 0x00
 178          n | Comment
 179          1 | 0x00
 180          4 | Checksum? (seems to be 0x00000000 if comment empty)
 181
 182 Then, read type 0 for confirmation.
 183 Then, sendClose() (0xa response: 5x 00).
 184
 185
 186 6c - Request size on disk (?)
 187 ------------------------------------
 188
 189 Payload:
 190
 191      Bytes | Content
 192     -------|--------------------
 193          n | Path
 194          1 | 0x00
 195
 196 Then, read type 0 for confirmation.
 197 Then, read type 9 for 12 bytes of payload (### TODO ###).
 198 Then, send type 0 to request more data (no payload).
 199 Then, read type 9 for 12 bytes of payload (### TODO ###).
 200 Then, send type 0 to request more data (no payload).
 201 Then, read type 0 signaling end of attributes (no payload).
 202 Then, sendClose() (0xa response: 5x 00).
 203
 204 OR
 205
 206 Then, read type 0 for confirmation.
 207 Then, read type 0 signaling end of attributes (no payload).
 208 Then, sendClose() (0xa response: 5x 00).
 209
 210
 211
 212 6d - Close file
 213 ----------------
 214
 215 No payload.
 216
 217 Then, read type 0x0a for confirmation (typical payload: 5 bytes of 0x00).
 218
 219 This is used to finish an operation, such as a directory listing
 220 or renaming a file.
 221
 222
 223 6e - Format disk
 224 -----------------
 225
 226 ### TODO ###
 227
 228
 229 6f - New folder
 230 ----------------
 231
 232 Payload:
 233
 234      Bytes |  Content
 235     -------|--------------------
 236          n | Parent path
 237          1 | 0x00
 238
 239 Then, read type 0 for confirmation.
 240 Then, sendClose() (0xa response: 5x 00).
 241
 242 The host will create a new folder in the given path, together with a
 243 matching .info file.
 244 The folder name cannot be chosen, and will be something like "Unnamed1".
 245
 246 To create a folder with a specific name, use 0x66.
 247 Note that 0x66'ing a folder does not seem to set its time.