From 34f64cb2059744da43cee540d5041037872996ca Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 16 Mar 2015 16:22:00 +0100 Subject: rename README as protocol --- xul-ext/README | 109 ------------------------------------------------------- xul-ext/protocol | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 109 deletions(-) delete mode 100644 xul-ext/README create mode 100644 xul-ext/protocol diff --git a/xul-ext/README b/xul-ext/README deleted file mode 100644 index b29e2fd..0000000 --- a/xul-ext/README +++ /dev/null @@ -1,109 +0,0 @@ -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 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 -- cgit v1.2.3