aboutsummaryrefslogtreecommitdiffstats
path: root/xul-ext
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2015-03-16 02:58:40 +0100
committerGuilhem Moulin <guilhem@fripost.org>2015-03-16 02:58:40 +0100
commit8ad92a40f82595f8b64f022aa3628fbbc882c3e8 (patch)
treed71a9b0c030838634adb91df983e20b42b5ccbfb /xul-ext
parent3750346a8e8736c726e6ad8fcb8ad82d81975fbc (diff)
Document the protocol.
Diffstat (limited to 'xul-ext')
-rw-r--r--xul-ext/README107
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