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