socket_format.txt (5378B)
1 General: 2 3 All requests, responses, errors, and events start with a sequence number. 4 This number starts at 0 and is incremented by the client with each request. 5 When the server sends a response, error, or event, it starts with the last 6 sequence number that the client sent. The client 'ltkc' adds sequence 7 numbers automatically (perhaps it should hide them in its output as well, 8 but I'm too lazy to implement that right now). A more advanced client could 9 use the numbers to properly check that requests really were received. 10 It isn't clear yet what should happen in the pathological case that the 11 uint32_t used to store the sequence number overflows before any of the 12 requests have been handled (i.e. it isn't clear anymore which request a 13 reply is for). I guess this could technically happen when running over a 14 broken connection or something, but I don't have a solution right now. 15 It doesn't seem like a very realistic scenario, though, considering that 16 all the requests/responses would need to be buffered somewhere, which 17 would be somewhat unrealistic considering the size of uint32_t. 18 19 Requests: 20 21 <widget type> <widget id> <command> <args> 22 > grid grd1 create 2 2 23 24 If the command takes a string, the string may contain newlines: 25 > button btn1 create "I'm a 26 > button!" 27 28 The command line is read until the first newline that is not 29 within a string. 30 31 Double quotes must be escaped in strings, like so: 32 > button btn1 create "Bla\"bla" 33 34 Essentially, the individual messages are separated by line 35 breaks (\n), but line breaks within strings don't break the 36 message. 37 38 Responses: 39 40 Not properly implemented yet. 41 Currently, all requests that don't generate errors just get the response 42 "<sequence> res ok". Of course, this will be changed once other response 43 types are available (e.g. get-text and others). 44 45 It might be good to allow ignoring responses to avoid lots of useless traffic. 46 On the client side, the usage could be similar to XCB's checked/unchecked. 47 48 Errors: 49 50 err <error number> <number of bad argument or -1> <string description of error> 51 52 Events: 53 54 event[l] <widget id> <widget type or "widget" for generic events> <event name> [further data] 55 56 By default, no events are reported. An event mask has to be set first: 57 58 mask-add <widget id> <type> <event name> [lock] 59 mask-remove <widget id> <type> <event name> [lock] 60 mask-set <widget id> <type> <event name> [lock] 61 62 <type> is either "widget" for generic events (mousepress, mouserelease, 63 mousemotion, resize, statechange) or the widget type for specific events. 64 The only specific event currently supported is "press" for both "button" 65 and "menuentry". Note that currently, only a single mask type can be 66 added/removed at once instead of combining multiple in one request 67 (i.e. it isn't possible to do something like "mousepress|mouserelease" yet). 68 69 If "lock" is set, the "lock mask" is manipulated instead of the normal one. 70 If an event occurs that is included in the lock mask, the event will start 71 with "eventl" instead of "event", and the ltk server blocks until it gets the 72 request "event-unlock [true/false]" from the client that received the event. 73 Note that if multiple clients have an event in their lock mask, all of them will 74 receive the event, but only one of them is chosen to listen for the event-unlock 75 (basically, this is unspecified behavior that should be avoided). If event-unlock 76 includes "true", the event is not processed further by the ltk server. If "false" 77 is given instead, the event is processed as usual by the ltk server. 78 79 This was added to allow functionality like in regular GUI toolkits where it is 80 possible to override events completely. The problem is that it currently isn't 81 really clear where exactly the command should be emitted and whether it really 82 makes sense to block all further processing (some processing has to be done 83 even now for it to make any sense at all). That could possibly lead to very 84 weird bugs. It also currently isn't possible to do much after locking because 85 no useful low-level functions for widgets exist (yet?). All in all, I'm not 86 entirely sure how to make this work nicely so it is actually useful. 87 Since all of this is pushed over a socket and will probably be able to run 88 over a network connection eventually, it will also cause problems with latency. 89 90 Miscellaneous: 91 92 It probably isn't too great for security when anyone can do anything with the 93 window. Maybe it would be better to allow different clients to have different 94 permissions? For instance, maybe only the main client could change things, but 95 other clients could have readonly permissions for things like screenreaders. 96 That would probably get very over-complicated, though. 97 98 I'm also seriously considering switching to a binary socket format. It's nice 99 to have a text format, but it's an absolute pain to process, because everything 100 has to be converted from/to text. It also isn't nearly as efficient, especially 101 if more complicated things are done, such as listening for all mousemotion events. 102 Of course, it could be made much more efficient with various lookup tables 103 (it isn't implemented very efficiently currently), but still not nearly as good 104 as a binary protocol. The idea would be to have a binary protocol, but to still 105 have something like ltkc that converts the protocol to a text format so simple 106 shell clients can still exist, but more complicated programs aren't hindered by it.