diff options
| -rw-r--r-- | xul-ext/README | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/xul-ext/README b/xul-ext/README new file mode 100644 index 0000000..1d08374 --- /dev/null +++ b/xul-ext/README @@ -0,0 +1,107 @@ +Upon startup, Firefox creates and listens on a new UNIX socket (shared +accross all tabs and windows) on which commands can be thrown in to fill +HTML forms. The greeting message indicates that the server is ready to +accept commands. Each command and response are single UTF8-encoded +lines ending with a newline character `\n'. Each reponse consists of a +code (OK, ERROR, or BYE), together with an optional message. Each +command line yields to a single a response line, and commands may not be +sent in parallel: clients must wait for the response of a first command +before sending a second one. + +A OK response code indicates a successful greeting or client command, +and may be accompanied with a JSON-encoded message data. An ERROR +response code indicates a server or client protocol error, the reason of +which may be given as an accompanying UTF8 string. A BYE response code +indicates an imminent end to client connection. + + OK [' ' JSON-encoded-data] + ERROR ' ' UTF8String + BYE + + +The greeting message consists of the the URI (scheme://hostname:port) of +the active tab of the active window. (":port" is ommited for default +ports, e.g., 443 for https.) Said URI is then cached for the whole +session, utils the client disconnects or an REFRESH command is issued. +Hence subsequent GETFORMS and FILL commands are always relative to the +greeting or the most recent REFRESH response URI, and not the possibly +new active tab. The URI is JSON-encoded (and decodes as a string not an +object, which is an extension to RFC4627) hence non-printable and +control characters are excaped properly (but they are not valid in a +hostname anyway). + + S: OK ' ' JSON-encoded-URI + + +The REFRESH command clears the internal URI and HTML form caches, and +the server replies with the URI of the currently (active) tab of the +(currently) active window. See the greeting message above for details. + + C: REFRESH + S: OK ' ' JSON-encoded-URI + + +The GETFORMS command yields a response message data consisting of the list of +all visible forms, with their method, action URI, and for each field of type +password, text or email, their name, type, value and maxLength (unless -1) +values: + + [ + { + "method": "POST", + "action": "https://mail.fripost.org/", + "fields": [ + { + "name": "_user", + "type": "text", + "value": "guilhem" + }, + { + "name": "_pass", + "type": "password", + "value": "top secret" + "maxLength": 32 + } + ] + } + ] + +The form list is kept in cache until the client closes the connection or +another GETFORMS command is issued. This ensure that subsequent FILL commands +are relatve to these forms even if the document has been modified. + + C: GETFORMS + S: OK JSON-encoded-array + + +The FILL command must be preceeded by a GETFORM command, and takes an index and +a JSON-encoded array of string as arguments. The index is that of the form one +wants to fill, and the array must be at most as long as there are of fields in +that form (as found in the most recent GETFORMS response). The value of +each such field is then updated with that found in the array (unless +null). + + C: FILL index JSON-encoded-array + S: OK + + +The QUIT command yields a BYE response. + + R: QUIT + S: BYE + + + +Example: + + S: OK "https://mail.fripost.org" + C: GETFORMS + S: OK [{"method":"POST","action":"https://mail.fripost.org/","fields":[{"name":"_user","type":"text","value":""},{"name":"_pass","type":"password","value":""}]}] + C: FILL 0 ["guilhem","topsecret"] + S: OK + C: GETFORM + S: ERROR Invalid command: GETFORM + C: GETFORMS + S: OK [{"method":"POST","action":"https://mail.fripost.org/","fields":[{"name":"_user","type":"text","value":"guilhem"},{"name":"_pass","type":"password","value":"topsecret"}]}] + C: QUIT + S: BYE |