aboutsummaryrefslogtreecommitdiffstats
path: root/xul-ext/protocol
diff options
context:
space:
mode:
Diffstat (limited to 'xul-ext/protocol')
-rw-r--r--xul-ext/protocol109
1 files changed, 109 insertions, 0 deletions
diff --git a/xul-ext/protocol b/xul-ext/protocol
new file mode 100644
index 0000000..b29e2fd
--- /dev/null
+++ b/xul-ext/protocol
@@ -0,0 +1,109 @@
+Upon startup, Firefox creates and listens on a new UNIX socket (shared
+between 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 string lines
+ending with a newline character `\n'. (JSON-encoding ensures that
+control characters are escaped properly; decoding to a string rather
+than an object is allowed here, although it extends RFC4627.) Each
+response consists of a code (OK, ERROR, or BYE), together with a
+JSON-encoded 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.
+
+An 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 JSON-encoded UTF8 string. A BYE
+response code indicates an imminent end to client connection.
+
+ S: OK [' ' JSON-encoded-data]
+ S: ERROR ' ' JSON-encoded-string
+ S: BYE
+
+
+The greeting message consists of the the URI (scheme://hostname:port) of
+the active tab of the active window. (":port" is omitted for default
+ports, e.g., 443 for https.) Said URI is then cached for the whole
+session, until 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, rather than the
+possibly new active tab. The URI is a JSON-encoded string.
+
+ 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 relative to these forms even if the document has been
+modified.
+
+ C: GETFORMS
+ S: OK JSON-encoded-array
+
+
+The FILL command must be preceded 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, and terminates the connection.
+
+ C: QUIT
+ S: BYE
+
+
+
+Example:
+
+ # client initiates the connection
+ 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
+ # client is disconnected