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, response or event.
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, response or event
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 form
Content-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, response or event
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_id field.

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_id field.

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] `onBreak`

Firebug 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] `onContextCreated`

Fired 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] `onContextDestroyed`

Fired 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] `onInspectNode`

handles 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] `onResume`

Fired when a context is resumed (after being suspended)

  { "seq":9,
    "type":"event",
    "event":"onResume",
    "context_id":"http://localhost:8080/test.html"
  }

[edit] `onScript`

Fired 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"
              }
            }
          }
        }
      ]
    }
  ]
}

Crossfire Protocol Reference

From FirebugWiki

Contents

[edit] Crossfire Protocol Reference

[edit] Handshake

[edit] Packet Format

[edit] JSON Message Format

[edit] Request Packets

[edit] Response Packets

[edit] Event Packets

[edit] Commands

[edit] version

[edit] listcontexts

[edit] lookup

[edit] backtrace

[edit] changebreakpoint

[edit] clearbreakpoint

[edit] continue

[edit] evaluate

[edit] frame

[edit] getbreakpoint

[edit] getbreakpoints

[edit] inspect

[edit] scope

[edit] scopes

[edit] script

[edit] scripts

[edit] setbreakpoint

[edit] source

[edit] suspend

[edit] Events

[edit] onBreak

[edit] onConsoleDebug

[edit] onConsoleError

[edit] onConsoleInfo

[edit] onConsoleLog

[edit] onConsoleWarn

[edit] onContextCreated

[edit] onContextDestroyed

[edit] onInspectNode

[edit] onResume

[edit] onScript

[edit] onToggleBreakpoint

[edit] Object Types

[edit] Types

Views

Personal tools

Search

Navigation

Panels

Extensions

Get Involved

Wiki

Toolbox

[edit] `onBreak`

[edit] `onConsoleDebug`

[edit] `onConsoleError`

[edit] `onConsoleInfo`

[edit] `onConsoleLog`

[edit] `onConsoleWarn`

[edit] `onContextCreated`

[edit] `onContextDestroyed`

[edit] `onInspectNode`

[edit] `onResume`

[edit] `onScript`

[edit] `onToggleBreakpoint`