WinPort/FarTTY.h

   1 #pragma once
   2
   3 /*** This particular file distributed under Public Domain terms. ***/
   4
   5 /** This file contains main definitions of commands used by far2l TTY extensions,
   6  * as well as some documentation for them.
   7  */
   8
   9 ////////////////////
  10 /**
  11 FARTTY_INTERACT_* commands are send from client to server to request it to perform some action.
  12 Request looks as "\x1b_far2l:"BASE64-encoded-arguments-stack"\x07"
  13 For details of arguments stack encoding see utils/StackSerializer.h and utils/StackSerializer.cpp.
  14 Each request's stack has on top 8-bit ID followed by any of FARTTY_INTERACT_* and related arguments.
  15 If request ID is zero then server doesnt reply on such request, if ID is not zero then upon its
  16 completion server sends back to client reply that has similar encoding and same ID on top of its
  17 arguments stack, however other reply's arguments represent result of requested operation.
  18 Note that in descriptions below arguments are listed in stack top->bottom order.
  19 All integer values are in little-endian format.
  20 */
  21
  22 /** Initiates ad-hoc copy-to-clipboard starting at last mouse click position
  23  In: N/A
  24  Out: N/A
  25 */
  26 #define FARTTY_INTERACT_CONSOLE_ADHOC_QEDIT       'e'
  27
  28 /** Maximizes window
  29  In: N/A
  30  Out: N/A
  31 */
  32 #define FARTTY_INTERACT_WINDOW_MAXIMIZE           'M'
  33
  34 /** Makes window to be not-maximized
  35  In: N/A
  36  Out: N/A
  37 */
  38 #define FARTTY_INTERACT_WINDOW_RESTORE            'm'
  39
  40 /** Various operations with clipboard, see also FARTTY_INTERACT_CLIP_*
  41  In:
  42   char (FARTTY_INTERACT_CLIP_* subcommand)
  43   ..subcommands-specific
  44  Out:
  45   ..subcommands-specific
  46 */
  47 #define FARTTY_INTERACT_CLIPBOARD                 'c'
  48
  49 /** Changes height of cursor in percents
  50  In:
  51   uint8_t (cursor height to set from 0% to 100%)
  52  Out: N/A
  53 */
  54 #define FARTTY_INTERACT_SET_CURSOR_HEIGHT         'h'
  55
  56 /** Gets maximum possible size of window
  57  In: N/A
  58  Out:
  59   uint16_t (height)
  60   uint16_t (width)
  61 */
  62 #define FARTTY_INTERACT_GET_WINDOW_MAXSIZE        'w'
  63
  64 /** Displays desktop notification with given title and text
  65  In:
  66   string (title)
  67   string (text)
  68  Out: N/A
  69 */
  70 #define FARTTY_INTERACT_DESKTOP_NOTIFICATION      'n'
  71
  72 /** Sets titles of F-keys board if host supports this (invented for Mac touchbar)
  73  In:
  74   12 elements each is either [uint8_t (state) = 0] either [uint8_t (state) != 0; string (F-key title)]
  75  Out:
  76   bool (true on success; false if operation impossible)
  77 */
  78 #define FARTTY_INTERACT_SET_FKEY_TITLES           'f'
  79
  80 /** Request color palette info
  81  In:
  82   N/A
  83  Out:
  84    uint8_t maximum count of color resolution bits supported (4, 8, 24)
  85    uint8_t reserved and set to zero, client should ignore it
  86 */
  87 #define FARTTY_INTERACT_GET_COLOR_PALETTE         'p'
  88
  89
  90 /** Declares that client supports specified extra features, so server _may_ change its hehaviour accordingly if it also supports some of them
  91  In:
  92   uint64_t (set of FARTTY_FEAT_* bit flags)
  93  Out: N/A
  94 */
  95 #define FARTTY_INTERACT_CHOOSE_EXTRA_FEATURES     'x'
  96
  97 ///////////////////////
  98 /** Clipboard operations.
  99 Synopsis:
 100
 101  Usecase - put text into clipboard in single transaction:
 102   CLIP_OPEN(PASSCODE) -> (STATUS)
 103   CLIP_SETDATA(CF_TEXT, UTF8 encoded text) -> (STATUS, ID of retrieved data)
 104   CLIP_CLOSE -> STATUS
 105
 106  Put text into clipboard in multiple transaction:
 107   CLIP_OPEN(PASSCODE) -> (STATUS)
 108   CLIP_SETDATACHUNK(first part of UTF8 encoded text)
 109   CLIP_SETDATACHUNK(second part of UTF8 encoded text)
 110   ...
 111   CLIP_SETDATA(CF_TEXT, last part of UTF8 encoded text) -> (STATUS, ID of stored data)
 112   CLIP_CLOSE -> (STATUS)
 113
 114  Check if there text on clipboard:
 115   CLIP_ISAVAIL(CF_TEXT) -> (TRUE or FALSE)
 116
 117  Get ID of text on clipboard:
 118   CLIP_OPEN(PASSCODE) -> (STATUS)
 119   CLIP_GETDATAID(CF_TEXT) -> (STATUS, ID of remote data)
 120   CLIP_CLOSE -> (STATUS)
 121
 122  Get text from clipboard:
 123   CLIP_OPEN(PASSCODE) -> (STATUS)
 124   CLIP_GETDATA(CF_TEXT) -> (STATUS, UTF8 encoded text, ID of retrieved data)
 125   CLIP_CLOSE -> (STATUS)
 126
 127
 128 Glossary:
 129
 130  Passcode - random string that client sends to server to identify itself. Server on its side may
 131   ask user for allowing clipboard access and may use this passcode to remember user's choice.
 132   Its recommended to remember passcode on server side on per-client identity basis, to protect
 133   against malicious client that somehow stolen other client's passcode.
 134
 135  Clipboard format ID - value that describes kind of data to be transferred. ID can be predefined
 136   or dynamically registered. In first case it describes some well-known data format, in another -
 137   data is treated by protocol as opaque BLOB.
 138   Predefined ID values used by far2l based on Win32 IDs, but with some modifications, currently
 139   only following predefined values are used by far2l in reality:
 140    1  - CF_TEXT - text encoded as UTF8
 141    13 - CF_UNICODETEXT - text encoded as UTF32 (depcrecated in recent releases in favor of CF_TEXT)
 142    Also far2l dynamically registers some own data formats to copy-paste vertical text blocks etc.
 143     At same moment of time clipboard may contain several different formats, thus allowing data to be
 144     represented in different forms. Also CF_TEXT/CF_UNICODETEXT transparently transcoded if needed.
 145
 146  Clipboard data ID - 64-bit value that uniquely corresponds to data, currently its implemented as
 147   crc64 of data. It can be used by client to check if clipboard contains same data as client has in
 148   its own cache and thus allows to avoid duplicated network transfers.
 149 */
 150
 151 /** Authorizes clipboard accessor and opens clipboard for any subsequent operation.
 152  In:
 153   string (32 <= length <= 256 - random client ID used as passcode in subsequent clipboard opens)
 154  Out:
 155   int8_t (1 - success, 0 - failure, -1 - access denied)
 156   uint64_t OPTIONAL (combination of FARTTY_FEATCLIP_* supported by server)
 157 */
 158 #define FARTTY_INTERACT_CLIP_OPEN                  'o'
 159
 160 /** Closes clipboard, must be used to properly finalize required clipboard action.
 161  In: N/A
 162  Out:
 163   int8_t (1 - success, 0 - failure, -1 - clipboard wasn't open)
 164 */
 165 #define FARTTY_INTERACT_CLIP_CLOSE                 'c'
 166
 167 /** Empties clipboard.
 168  In: N/A
 169  Out:
 170   int8_t (1 - success, 0 - failure, -1 - clipboard wasn't open)
 171 */
 172 #define FARTTY_INTERACT_CLIP_EMPTY                 'e'
 173
 174 /** Checks if given format available for get'ing from clipboard.
 175  In: uint32_t - format ID
 176  Out: int8_t (1 - there is data of such format, 0 - there is no data of such format)
 177 */
 178 #define FARTTY_INTERACT_CLIP_ISAVAIL               'a'
 179
 180 /** Allows chunked clipboard data setting by sendings multiple chunks before final SETDATA.
 181  Special case: chunk with zero size treated as dismissing all previously queued chunks.
 182  OPTIONAL: can be used only if server reported FARTTY_FEATCLIP_CHUNKED_SET as supported feature
 183  In:
 184   uint16_t (chunk's data size, shifted right by 8 bits)
 185   data of specified size
 186  Out: N/A
 187 */
 188 #define FARTTY_INTERACT_CLIP_SETDATACHUNK          'S'
 189
 190 /** Puts into clipboard data of specified format. Prepends given data with pending chunks (if any).
 191  In:
 192   uint32_t (format ID)
 193   uint32_t (size of data)
 194   data of specified size
 195  Out:
 196   int8_t (1 - success, 0 - failure, -1 - clipboard wasn't open)
 197   uint64_t OPTIONAL (clipboard data ID, only if server reported FARTTY_FEATCLIP_DATA_ID)
 198 */
 199 #define FARTTY_INTERACT_CLIP_SETDATA               's'
 200
 201 /** Gets from clipboard data of specified format.
 202  In:
 203   uint32_t (format ID)
 204  Out:
 205   uint32_t (0 - on failure, -1 - clipboard wasn't open, other value - size of data - on success)
 206   data of specified size
 207   uint64_t OPTIONAL (clipboard data ID, only if server reported FARTTY_FEATCLIP_DATA_ID)
 208 */
 209 #define FARTTY_INTERACT_CLIP_GETDATA               'g'
 210
 211 /** Gets ID of current clipboard data of specified format.
 212  OPTIONAL: can be used only if server reported FARTTY_FEATCLIP_DATA_ID as supported feature
 213  In:
 214   uint32_t (format ID)
 215  Out:
 216   uint64_t (0 - failure, nonzero value - clipboard data ID)
 217 */
 218 #define FARTTY_INTERACT_CLIP_GETDATAID             'i'
 219
 220 /** Registers arbitrary clipboard data format.
 221  In:
 222   string (format name to be registered)
 223  Out:
 224   uint32_t (0 - failure, nonzero value - registered format ID)
 225 */
 226 #define FARTTY_INTERACT_CLIP_REGISTER_FORMAT       'r'
 227
 228 ///////////////////////
 229
 230 /** Client may specify this wanted extra feature if it supports compact input events.
 231  If server supports this feature it may send such events, however client should be ready to
 232  receive not-compact events as well.
 233 */
 234 #define FARTTY_FEAT_COMPACT_INPUT             0x00000001
 235
 236 /** Client may specify this wanted extra feature if it supports in-band terminal size events.
 237  If server supports this feature it may send such events, however client should be ready to
 238  handle usual SIGWINCH signals as well.
 239 */
 240 #define FARTTY_FEAT_TERMINAL_SIZE             0x00000002
 241
 242 /** Server reports this on responce of FARTTY_INTERRACT_CLIP_OPEN if it supports clipboard data ID.
 243  Clipboard data ID allows client-side caching of clipboard data to avoid known data transfers.
 244 */
 245 #define FARTTY_FEATCLIP_DATA_ID               0x00000001
 246
 247 /** Server reports this on response of FARTTY_INTERACT_CLIP_OPEN if it supports chunked clipboard data set.
 248  This feature allows client to implement background and cancellable clipboard copy.
 249 */
 250 #define FARTTY_FEATCLIP_CHUNKED_SET           0x00000002
 251
 252 ///////////////////////
 253 /**
 254 FARTTY_INPUT_* notifications are send from server to client to inform about specific event happened.
 255 Notification looks as "\x1b_f2l:"BASE64-encoded-arguments-stack"\x07"
 256 For details of arguments stack encoding see utils/StackSerializer.h and utils/StackSerializer.cpp.
 257 Unlike FARTTY_INTERACT_* there is no ID and no replies are expected from client to server,
 258 all arguments are defined by FARTTY_INPUT_* notification ID - see below (stack top->bottom order).
 259 */
 260
 261
 262 /** Server sends this to inform about mouse event. See MOUSE_EVENT_RECORD for details.
 263   uint32_t (dwEventFlags)
 264   uint32_t (dwControlKeyState)
 265   uint32_t (dwButtonState)
 266   int16_t (pos.Y)
 267   int16_t (pos.X)
 268 */
 269 #define FARTTY_INPUT_MOUSE                    'M'
 270
 271 /** Server sends this to inform about mouse event if compact input is enabled and possible. See MOUSE_EVENT_RECORD for details.
 272   uint8_t (dwEventFlags)
 273   uint8_t (dwControlKeyState)
 274   uint16_t (dwButtonState encoded as: (dwButtonState & 0xff) | ( (dwButtonState >> 8) & 0xff00))
 275   int16_t (pos.Y)
 276   int16_t (pos.X)
 277 */
 278 #define FARTTY_INPUT_MOUSE_COMPACT            'm'
 279
 280 /** Server sends this to inform about keydown or keyup event. See KEY_EVENT_RECORD for details.
 281   uint32_t (UTF32 code)
 282   uint32_t (dwControlKeyState)
 283   uint16_t (wVirtualScanCode)
 284   uint16_t (wVirtualKeyCode)
 285   uint16_t (wRepeatCount)
 286 */
 287 #define FARTTY_INPUT_KEYDOWN                  'K'
 288 #define FARTTY_INPUT_KEYUP                    'k'
 289
 290 /** Server sends this to inform about keydown or keyup event if compact input is enabled and possible.
 291   See KEY_EVENT_RECORD for details. Note that event doesn't specify wVirtualScanCode and wRepeatCount
 292   thus client must use Virtual Key Code to Virtual Scan Code translation and assume wRepeatCount = 1
 293   uint16_t (UTF32 code fit to uint16_t)
 294   uint16_t (dwControlKeyState fit to uint16_t)
 295   uint8_t (wVirtualKeyCode fit to single-byte)
 296 */
 297 #define FARTTY_INPUT_KEYDOWN_COMPACT          'C'
 298 #define FARTTY_INPUT_KEYUP_COMPACT            'c'
 299
 300 /** Server sends this to inform about recent terminal size.
 301   uint16_t (terminal width)
 302   uint16_t (terminal height)
 303 */
 304 #define FARTTY_INPUT_TERMINAL_SIZE          'S'