Crossfire Protocol Reference
From FirebugWiki
[edit] Crossfire Protocol Reference
[edit] Handshake
Once a connection has been established with a remote host,
Crossfire will wait until it receives a UTF-8 string which
matches CrossfireHandshake\r\n
[edit] Packet Format
Crossfire packets contain a content-length header with key
Content-Length followed by a colon (:),
and the number of characters (in decimal) contained in the message body.
The body of the packet is a UTF-8 string containing a JSON-formatted message.
Packet headers and body are separated by a CRLF (\r\n).
Packets are terminated by a CRLF (\r\n) after the body.
Example:
Content-Length:69\r\n { "context_id":null, "type":"request", "seq":1, "command":"listcontexts" }\r\n
Version 0.3 adds an extra CRLF (\r\n) between the headers area and the content to be more like HTTP:
Example:
Content-Length:69\r\n \r\n { "context_id":null, "type":"request", "seq":1, "command":"listcontexts" }\r\n
[edit] JSON Message Format
Message bodies are JSON-formatted strings which contain at a minimum, the context ID, sequence number, and packet type.
- context_id
- String that identifies which JavaScript context the packet applies to. For a Web page, this may be the URL of the page.
- seq
- sequence number (integer)
- type
- packet type; one of
"request","response", or"event"
[edit] Request Packets
A request packet includes a command name and an arguments object containing any arguments specific to the command.
All request packets have the general form:
Content-Length:<length> \r\n { "type":"request", "command":<command>, "context_id":<context_id> "seq":<packet_sequence>, "arguments":{<argument_list>} }
- type
- the kind of the packet - one of
request,responseorevent.- command
- command name of the request. A complete listing of requests that can be used in
<command>are available in the Commands section.- context_id
- the id of the context the request is made against. Not all requests use a context.
- seg
- the packet sequence number. Sequence numbers start at zero an increment monotonically as long as the session is active
- arguments
- JSON object - named arguments map
example:
Content-Length:219 \r\n { "type":"request", "command":"setbreakpoint", "context_id":"http://localhost:8080/test.html", "seq":21, "arguments": { "position":0, "enabled":true, "target":"http:/localhost:8080/test/some_javascript.js", "line":9, "ignoreCount":0, "type":"line" } } \r\n
[edit] Response Packets
A response packet will contain the sequence number of the original request and the name of the command, as well as the body of the response and booleans indicating the running status and whether the request was successful.
All response packets are of the form:Content-Length:<length> \r\n { "type":"response", "command":<command>, "seq":<packet_sequence>, "request_seq":<request_sequence>, "running":<is_running>, "success":<success_status>, "body":{} }
- type
- the kind of the packet - one of
request,responseorevent- command
- command name of the request
- seq
- the packet sequence number. Sequence numbers start at zero an increment monotonically as long as the session is active
- request_seq
- request sequence number (integer)
- running
- boolean
- success
- boolean
- body
- JSON object, mapping that contains the information requested, or an empty map if the original request did not succeed
example:
Content-Length:80 \r\n { "type":"response", "command":"listcontexts", "seq":2, "request_seq":1, "running":true, "success":true, "body":{ "contexts":["http://localhost:8080/test.html"] } } \r\n
[edit] Event Packets
Event packets contain the name of the event and a 'data' object which may contain more information related to the event.
All event packets are of the formContent-Length:<length> \r\n "type":"event", "event":<event>, "context_id":<context_id>, "seq":<packet_sequence>, "data":{<data_object>} \r\n
- type
- the kind of the packet - one of
request,responseorevent- event
- name of the event
- context_id
- the id of the context this event applies to
- seq
- the packet sequence number. Sequence numbers start at zero an increment monotonically as long as the session is active
- data
- JSON object containing additional data about the event
example
Content-Length:122 \r\n { "type":"event", "event":"onContextCreated", "context_id":"xf0.1a::9931113", "seq":5, "data":{ "href":"http://www.google.ca/" } } \r\n
[edit] Commands
-
[edit] version
Returns the Crossfire protocol version. This command does not require a
context_idfield.request
An example of the request you send:
Content-Length:46 \r\n { "type":"request", "command":"version", "seq":2 } \r\n
response
An example of the response you will receive:
Content-Length:119 \r\n { "type":"response", "command":"version", "seq":3, "request_seq":2, "running":true, "success":true, "body":{ "version":"0.1a" } } \r\n
-
[edit] listcontexts
Returns a list of context id's. This command does not require a
context_idfield.request
An example of the request you send:
Content-Length:51 \r\n { "type":"request", "command":"listcontexts", "seq":3 } \r\n
response
An example of the response you receive:
Content-Length:121 \r\n { "type":"response", "command":"listcontexts", "seq":4, "request_seq":3, "running":true, "success":true, "body":{ "contexts":[] } } \r\n
-
[edit] lookup
Looks up an object by its handle.
request An example of the request you send:
response An example of the response you receive:
-
[edit] backtrace
Returns a backtrace (stacktrace) of frames.
request
An example of the request you send:
Content-Length:128 \r\n { "type":"request", "command":"backtrace", "context_id":"xf0.1a::9931113", "seq":6, "arguments":{ "fromFrame":0, "includeScopes":true } } \r\n
response
An example of the response you receive:
-
[edit] changebreakpoint
Return the breakpoint object with the specified id.
request An example of the request you send:
response An example of the response you receive:
-
[edit] clearbreakpoint
Remove the breakpoint object with the specified id.
request An example of the request you send:
response An example of the response you receive:
-
[edit] continue
Continue execution of javascript if suspended, if no stepaction is passed, simply resumes execution.
request An example of the request you send:
response An example of the response you receive:
-
[edit] evaluate
Evaluates a JavaScript expression, either in the global scope, or optionally in a given frame if it exists.
request An example of the request you send:
response An example of the response you receive:
Example command:
{ "context_id": "xf0.1a::6621048", "type": "request", "command": "evaluate", "seq":30, "arguments": { "expression":"Math.PI*2" } }
And response:
{ "body": { "context_id": "xf0.1a::6621048", "result": 6.2831853071795862 }, "command": "evaluate", "context_id": "xf0.1a::6621048", "request_seq": 30, "running": true, "seq": 31, "success": true, "type": "response" }
-
[edit] frame
Returns a frame.
request An example of the request you send:
response An example of the response you receive:
-
[edit] getbreakpoint
Return the breakpoint object with the specified id.
request An example of the request you send:
response An example of the response you receive:
-
[edit] getbreakpoints
Return all the breakpoints in this context.
request An example of the request you send:
response An example of the response you receive:
-
[edit] inspect
Tells Firebug to enter 'inspect' mode.
request An example of the request you send:
response An example of the response you receive:
-
[edit] scope
Returns a particular scope for the specified frame.
request An example of the request you send:
response An example of the response you receive:
-
[edit] scopes
Returns all the scopes for a frame.
request An example of the request you send:
response An example of the response you receive:
-
[edit] script
Retrieve a single script
request An example of the request you send:
response An example of the response you receive:
-
[edit] scripts
Retrieve all known scripts in a context.
request An example of the request you send:
response An example of the response you receive:
Example:
{ "body": { "context_id": "xf0.1a::6621050", "scripts": [ { "columnOffset": 0, "compilationType": "top-level", "id": "http://getfirebug.com/install.js", "lineCount": 0, "lineOffset": 0, "sourceLength": 13 }, { "columnOffset": 0, "compilationType": "top-level", "id": "http://getfirebug.com/", "lineCount": 0, "lineOffset": 0, "sourceLength": 63 }, { "columnOffset": 0, "compilationType": "event", "id": "http://getfirebug.com//event/seq/1", "lineCount": 0, "lineOffset": 0, "sourceLength": 6 }, { "columnOffset": 0, "compilationType": "event", "id": "http://getfirebug.com//event/seq/2", "lineCount": 0, "lineOffset": 0, "sourceLength": 3 }, { "columnOffset": 0, "compilationType": "event", "id": "http://getfirebug.com//event/seq/3", "lineCount": 0, "lineOffset": 0, "sourceLength": 3 } ] }, "command": "scripts", "context_id": "xf0.1a::6621050", "request_seq": 48, "running": true, "seq": 49, "success": true, "type": "response" }
-
[edit] setbreakpoint
Set a breakpoint and return its id.
request An example of the request you send:
response An example of the response you receive:
-
[edit] source
source command.
request An example of the request you send:
response An example of the response you receive:
-
[edit] suspend
Try to suspend any currently running JavaScript.
request An example of the request you send:
Content-Length:77 \r\n { "type":"request", "command":"suspend", "context_id":"xf0.1a::9931113", "seq":5, } \r\n
response An example of the response you receive:
Content-Length:105 \r\n { "type":"response", "command":"suspend", "seq":6, "request_seq":5, "running":true, "success":true, "body":{}, }
[edit] Events
-
[edit]
onBreakFirebug has paused ("broken") in a script.
{ "seq":4, "type":"event", "event":"onBreak", "data" : { "url":"http://localhost:8080/test/some_javascript.js", "line":7 }, "context_id":"http://localhost:8080/test.html" }
-
[edit]
onConsoleDebug{ "seq":34, "type":"event", "event":"onConsoleDebug", "context_id":"http://localhost:8080/test.html", "data": { "0": { "member": "aMember" } } }
-
[edit]
onConsoleError{ "seq":28, "type":"event", "event":"onConsoleError","context_id":"http://localhost:8080/test.html", "data": { "0": { "source":"with(_FirebugCommandLine){syntax error\u000a};", "message":"missing ; before statement", "fileName":"http://localhost:8080/test.html", "lineNumber":71, "name":"SyntaxError", "stack":"eval(\"with(_FirebugCommandLine){syntax error\\n};\")@:0\u000a(\"with(_FirebugCommandLine){syntax error\\n};\")@http://localhost:8080/test.html:71\u000a_firebugEvalEvent([object Event])@http://localhost:8080/test.html:60\u000a" } } }
-
[edit]
onConsoleInfo{ "seq":6, "type":"event", "event":"onConsoleInfo", "context_id":"http://localhost:8080/test.html", "data": {"0":"The square root of 21 is 4.58257569495584"} }
-
[edit]
onConsoleLog{ "seq":27, "type":"event", "event":"onConsoleLog", "context_id":"http://localhost:8080/test.html", "data": { "0": "I did something!" } }
-
[edit]
onConsoleWarn{ "seq":23, "type": "event", "event":"onConsoleWarn", "context_id":"http://localhost:8080/test.html", "data":{"0":"bzzzt!"} }
-
[edit]
onContextCreatedFired when a new context is created in Firebug (ex: A new tab was opened and firebug was activated)
{ "seq":21, "type": "event", "event":"onContextCreated", "context_id":"xf0.2::6307226", "data":{"href":"http://localhost:8080/test.html"} }
-
[edit]
onContextDestroyedFired when a Firebug has destroyed a context (ex: Deactivate firebug has been pressed on a tab)
{ "seq":22, "type": "event", "event":"onContextDestroyed", "context_id":"xf0.2::6307226", }
-
[edit]
onInspectNodehandles onInspectNode event.
{ "seq":32, "type":"event", "event":"onInspectNode", "context_id":"http://localhost:8080/test.html", "data": { "node":"/html[1]/body[1]/p[4]/input[1]" } }
-
[edit]
onResumeFired when a context is resumed (after being suspended)
{ "seq":9, "type":"event", "event":"onResume", "context_id":"http://localhost:8080/test.html" }
-
[edit]
onScriptFired when a new script is compiled
handles onResume event.
{ "seq":9, "type":"event", "event":"onScript", "context_id":"http://localhost:8080/test.html" "data":{"href":"http://localhost:8080/scripts/testScript","context_href":"http://localhost:8080/scripts/"} }
-
[edit]
onToggleBreakpoint{ "seq":22, "type":"event", "event":"onToggleBreakpoint", "context_id":"http://localhost:8080/test.html" }
[edit] Object Types
Commands like frame, backtrace, scope, lookup will contain serialized Javascript values and objects in the body of the response. The JSON structure for these objects will always contain both a context_id and type field, and either a value field with a JSON value or, in the case of ref types, a handle field which can be used to obtain the actual value by using the lookup command.
[edit] Types
object function boolean number string undefined ref
Example: Frame Request Body
{ "context_id": "http://locahost:8080/test/test.html", "fromFrame": 0, "toFrame": 0, "totalFrames": 1, "frames":[ { "context_id: "http://locahost:8080/test/test.html", "index": 0, "func": "getRandom", "line": 23, "scopes": [ { "context_id": "http://locahost:8080/test/test.html", "index": 0, "frameIndex": 0, "object": { "context_id": "http://locahost:8080/test/test.html", "type":"object", "value":{ "random": { "context_id": "http://locahost:8080/test/test.html", "type": "number", "value": 65 }, "parent": { "context_id":"http://locahost:8080/test/test.html", "type": "ref", "handle": "1" } } } } ] } ] }
