Crossfire Protocol Reference

From FirebugWiki

Jump to: navigation, search

Contents

[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\r\n

If crossfire was started as a server it will reply with an acknowledgement that matches CrossfireHandshake\r\n\r\n.

The handshake can also be modified to include the names of tools that should be enabled when the server starts. More information about tool support and how to enabled / disable them can be found on the Tools API page.

[edit] Packet Format

Crossfire packets contain a content length header with key Content-Length: followed by the number of characters (in decimal) contained in the packet body. The packet body is a UTF-8 string containing a JSON-formatted object. A packet's header and body is separated by a double CRLF (\r\n\r\n), and its body is terminated by a CRLF (\r\n).

At a minimum, all packet bodies contain the following values:

"type" string The packet type, one of "request", "response" or "event".
"seq" number The packet's sequence number, relative to other packets of the same type.
"contextId" string The id of the packet's source or destination Context. Packets without a specific source or destination context can either omit this argument or can include it with a value of null.

Example packet with type 'request': 

Content-Length:69
\r\n\r\n
{
  "contextId":null,
  "type":"request",
  "seq":1,
  "command":"listcontexts"
}
\r\n

[edit] Request Packets

Request packets are sent from a client to a Crossfire server. They extend the basic Packet format with the following additional values:
"command" string The Command name.
"arguments" object The command-specific arguments accompanying the request.

Example: 

Content-Length:219
\r\n\r\n
{
  "type":"request",
  "command":"setbreakpoint",
  "contextId":"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

Response packets are sent from a Crossfire server to a client in response to a previous Request. They extend the basic Packet format with the following additional values:
"command" string The Command name from the original request.
"requestSeq" number The sequence number of the original request.
"body" object The command-specific values accompanying the response.
"status" object Information about the success/failure of performing the request, and the server's resulting state. This object contains the following values:
"code" required, number One of the following result codes:
CODE_OK = 0
CODE_MALFORMED_PACKET = 1
CODE_MALFORMED_REQUEST = 2
CODE_COMMAND_NOT_IMPLEMENTED = 3
CODE_INVALID_ARGUMENT = 4
CODE_UNEXPECTED_EXCEPTION = 5
CODE_COMMAND_FAILED = 6
CODE_INVALID_STATE = 7
"running" required, boolean Indicates whether Javascript is currently running on the server (as opposed to being suspended).
"message" optional, string A human-readable message, typically used to describe the cause of a failure.
"stackTrace" optional, string A human-readable stack trace, typically used to show information about an error that has occurred.

Example: 

Content-Length:80
\r\n\r\n
{
  "type":"response",
  "command":"listcontexts",
  "contextId":"xf0.1a::9931113",
  "seq":2,
  "request_seq":1,
  "running":true,
  "success":true,
  "body":{
           "contexts":["http://localhost:8080/test.html"]
         }
}
\r\n

[edit] Event Packets

Event packets are sent from a Crossfire server to a client to communicate a server-initiated event. They extend the basic Packet format with the following additional values:
"event" string The Event name.
"body" object The event-specific values accompanying the event.

Example: 

Content-Length:122
\r\n\r\n
{
  "type":"event",
  "event":"onContextCreated",
  "contextId":"xf0.1a::9931113",
  "seq":5,
  "body":{
           "href":"http://www.google.ca/"
         }
}

[edit] Values

The responses of commands like backtrace, frame, lookup and scopes contain serialized Javascript values. The JSON structure of these objects contains a type field, along with either a type-specific value field or, in the case of object and function values, a handle field whose value can be used to obtain the actual object/function with the lookup command.

[edit] object

An object is represented as a handle of the form: 
{
  "myobject":{
               "type":"object",
               "handle":<number>
             }
}

Objects can also be nested within other objects. For example in the case of a backtrace request, you will receive a response with variables split up as locals and 'this'.

Nested objects will always appear as a value entry in the object. For example: 

{
  "myobject":{
               "type":"object",
               "value":{
                         "mynestedobj":{"type":"object","handle":<number>}
                       }
             }
}

[edit] function

A function is represented as a handle of the form: 
{
  "myfunction":{
                 "type":"function",
                 "handle":<number>
               }
}

In versions of Crossfire less than 0.3a2 a function was represented as: 

{
  "myfunction":{
                 "type":"function",
                 "value":"function()"
               }
}

[edit] boolean

A boolean is represented as: 
{
  "myboolean":{
                "type":"boolean",
                "value":<true_or_false>
              }
}

[edit] number

A number is represented as: 
{
  "mynumber":{
               "type":"number",
               "value":<number_or_string>
             }
}

number_or_string must be either a number or one of "NaN", "Infinity" or "-Infinity".

[edit] string

A string is represented as: 
{
  "mystring":{
               "type":"string",
               "value":"string_value"
             }
}

[edit] undefined

An undefined value is represented as: 
{
  "myfunction":"undefined"
}

[edit] null

A null value is represented as: 
{
  "mystring":null
}

[edit] Objects

[edit] breakpoint

A breakpoint object describes a single breakpoint from Crossfire.
This object can be found in the getBreakpoints and setBreakpoints responses as well as the onToggleBreakpoint event. 
{
  "handle":<handle>,
  "type":<type>,
  "location":<location>,
  "attributes":<attributes>
}

Values

handle the Crossfire identifier for this breakpoint object
type the type of the breakpoint - for example line or error
location the object that contains location information
attributes the object of attributes that describe the breakpoint - for example enabled or condition

[edit] context

A context object describes a given context (tab) in Crossfire.
This object can be found in the listcontexts response. 
{
  "contextId":<context_id>,
  "url":<url>,
  "current":<is_current>
}

Values

context_id the id of the context
url the URL opened in the context (tab)
is_current if the context is the focus context

[edit] frame

A frame object describes a single stackframe from the debugger.
This object can be found in the backtrace and frame responses. 
{
  "index":<index>,
  "line":<line_number>,
  "functionName":<func_name>,
  "url":<url>,
  "locals":<variable_objects>,
  "scopes":<scope_array>
}

Values

index the index of the frame within the complete stack of frames from the debugger
line_number the line number the frame is currently suspended on
functionName the name of the function the frame is currently suspended in
url the URL of the script the frame is suspended in
locals the object containing the group of local variables for the frame
scopes the array of scope objects

[edit] scope

A scope object represents a logical grouping for a given set of local variables.
This object can be found in a stack frame object and in the scopes response. 
{
  "index": <index>,
  "frameIndex": <frame_index>,
  "scope": <scope_object>
}

Values

index the index of the scope in the complete array of scopes
frame_index the index of the frame this scope aligns with
closing_object the serialized object handle of the object that makes up this scope

[edit] script

A script object describes a single script.
This object can be found in the scripts response and the onScript event. 
{
  "url":<url>,
  "lineOffset":<line_offset>,
  "columnOffset":<column_offset>,
  "sourceLength":<source_length>,
  "lineCount":<line_count>,
  "type":<type>,
  "source":<source>
}

Values

url the URL of the script
line_offset the current line offset of the script within its parent (if any)
column_offset the current column offset of the script within its parent (if any)
source_length the entire length of the source for the script including all control characters
line_count the number of lines in the script
type the type of the compilation unit - see sourceFile.js for complete listing of types
source the complete source of the script

[edit] tool

A tool object describes a default or contributed tool.
This object can be found in the gettools, enabletools and disabletools responses. 
{
  "name":<name>,
  "enabled":<enabled_state>,
  "commands":<command_array>,
  "events":<event_array>,
  "desc":<description>
}

Values

name the name of the tool
enabled_state the enabled state of the tool (true or false)
command_array the array of the names of the commands this tool supports
event_array the array of the names of the events this tool is capable of sending
description the human-readable description of the tool

[edit] Commands

[edit] backtrace

[This command has been updated in Crossfire version 0.3a8, please see the migration guide entry for more information.]
Returns a backtrace (stacktrace) of frames when javascript is suspended.
Request Packet 'arguments' values:
"fromFrame" optional, number The 0-based frame index of the beginning of the range of frames to return. If this argument is omitted then the range will begin at the first frame.
"toFrame" optional, number The 0-based frame index of the end of the range of frames to return. If this argument is omitted, or if its value exceeds the index of the last available frame, then the range will end at the last available frame.
"includeScopes" optional, boolean Specifies whether the response should include Scopes for each of the returned frames. If this argument is omitted then the scopes will be included.

Example Request 

Content-Length:128
\r\n\r\n
{
  "type":"request",
  "seq":6,
  "command":"backtrace",
  "contextId":"xf0.1a::9931113",
  "arguments":{
                 "fromFrame":0,
                 "includeScopes":true
              }
}
\r\n

Response Packet 'body' values:

"frames" array of Frame objects The frames.
"fromFrame" number The 0-based frame index of the beginning of the range of returned frames.
"toFrame" number The 0-based frame index of the end of the range of returned frames.
"totalFrames" number The number of frames that are currently available in the suspended javascript.

Response Packet status codes:

CODE_OK The requested Frame objects were successfully returned.
CODE_INVALID_STATE Javascript execution is not currently suspended.

Example Response 

Content-Length:6325
\r\n\r\n
{
  "type":"response",
  "seq":50,
  "requestSeq":49,
  "command":"backtrace",
  "contextId":"xf0.3::4303985",
  "body":{
            "fromFrame":0,
            "toFrame":0,
	    "frames":[{
                         "index":0,
                         "functionName":"onload",
                         "url":"http://www.google.ca//event/seq/1",
                         "locals":{
                                     "this":{
                                               "screen":{"type":"object","handle":42},
                                               "screenLeft":{"type":"number","value":622},
                                               /* ...<snip>... */
                                            }
                                     /* ...<snip>... */
                                  },
                         "line":2,
                         "scopes":[{"index":0,"frameIndex":0,"object":{"type":"object","handle":348}}]
                     }],
            "totalFrames":1
         },
  "status":{
              "code":0,
              "running":false
           }
}
\r\n

[edit] changebreakpoint

This command has been superseded by changeBreakpoints.


[edit] changeBreakpoints

[This command has been updated in Crossfire version 0.3a8, please see the migration guide entry for more information.]
Changes the attributes of a set of breakpoints.
Request Packet 'arguments' values:
"handles" required, array of numbers The handles of the breakpoints to change.
"attributes" required, object The attributes to set or update on the breakpoints.

Example Request 

Content-Length:151
\r\n\r\n
{
  "type":"request",
  "seq":16,
  "command":"changeBreakpoints",
  "arguments":{
                 "handles":[1],
                 "attributes":{
                                 "enabled":true,
                                 "condition":"a == 7"
                              }
              },
}
\r\n

Response Packet 'body' values:

<none>

Response Packet status codes:

CODE_OK All of the specified breakpoint handles and attributes were valid, and the attributes were successfully changed on each of the breakpoints.
CODE_COMMAND_FAILED At least one of the specified breakpoint handles or attributes was not valid. Failure to change an attribute on a breakpoint could result from specifying an attribute name that does not apply to its type, or specifying an invalid attribute value (eg.- providing a string value for a boolean attribute). When this failure occurs none of the specified breakpoints have their attributes changed.

Example Response 

Content-Length:272
\r\n\r\n
{
  "type":"response",
  "seq":26,
  "requestSeq":16,
  "command":"changeBreakpoints",
  "body":{},
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] continue

Resumes execution of javascript that is suspended.
Request Packet 'arguments' values:
"stepAction" optional, string {'in', 'next', 'out'} Specifies the type of resume. Valid values are 'in' (step in), 'next' (step over) and 'out' (step out). Providing one of these values should result in a subsequent onBreak event being received once the specified javascript execution has occurred. If this argument is omitted then javascript execution is resumed with no expectation of breaking on a subsequent line.

Example Request: 

Content-Length:78
\r\n\r\n
{
  "type":"request",
  "seq":87,
  "command":"continue",
  "contextId":"xf0.3::2777681",
  "arguments":{}
}
\r\n

Response Packet 'body' values:

<none>

Response Packet status codes:

CODE_OK The specified resume happened successfully. Note that if a stepAction was provided then a subsequent onBreak event should be received once the specified javascript execution has occurred.
CODE_INVALID_STATE Javascript execution is not currently suspended.

Example Response

An example of the response you receive: 

Content-Length:105
\r\n\r\n
{
  "type":"response",
  "seq":8,
  "requestSeq":7,
  "command":"continue",
  "body":{},
  "status":{
              "code":0,
              "running":false
           }
}
\r\n

[edit] createContext

Requests that a new context be created. This context can be exposed to the user either by replacing an existing context with it or by attempting to create a new physical location for it (eg.- a new browser tab or window).
Request Packet 'arguments' values:
"contextId" optional, string The id of the Context to replace with this new context. If this argument is omitted then the server will attempt to create a new physical location (eg.- a browser tab or window) for the new context.
"url" required, string The URL to load into the new context.

Example Request: 

Content-Length:47
\r\n\r\n
{
  "type":"request",
  "seq":22,
  "command":"createContext",
  "arguments":{
                 "contextId":"xf0.1a::9931113",
                 "url":"http://www.google.com"
              }
}
\r\n

Response Packet 'body' values:

<none>

Response Packet status codes:

CODE_OK The new context was successfully created as requested.
CODE_COMMAND_FAILED The new context was not created. Possible causes of this include specification of an unknown contextId in the request, or failure of the server to create a new physical location for the new context.

Example Response

An example of the response you receive: 

Content-Length:120
\r\n\r\n
{
  "type":"response",
  "seq":23,
  "requestSeq":22,
  "command":"createContext",
  "body":{},
  "status":{
              "code":0,
              "running":true
           }
}

[edit] deletebreakpoint

This command has been superseded by deleteBreakpoints.

[edit] deleteBreakpoints

[This command has been updated in Crossfire version 0.3a8, please see the migration guide entry for more information.]
Deletes a set of breakpoints.
Request Packet 'arguments' values:
"handles" required, array of numbers The handles of the breakpoints to delete.

Example Request 

Content-Length:81
\r\n\r\n
{
  "type":"request",
  "seq":13,
  "command":"deleteBreakpoints",
  "arguments":{
                 "handles":[1]
              }
}
\r\n

Response Packet 'body' values:

<none>

Response Packet status codes:

CODE_OK All of the specified breakpoint handles were valid and were deleted.
CODE_COMMAND_FAILED At least one of the specified breakpoint handles was not valid. When this failure occurs none of the specified breakpoints are deleted.

Example Response 

Content-Length:232
\r\n\r\n
{
  "type":"response",
  "seq":15,
  "requestSeq":13,
  "command":"deleteBreakpoints",
  "body":{},
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] disableTools

Disables one or more known tools.
Request Packet 'arguments' values:
"tools" required, array of strings The names of the tools to disable. If any of the values are not valid (eg.- an unknown tool name) then none of the specified tools will become disabled. It is valid to attempt to disable a tool that is already disabled.

Example Request 

Content-Length:84
\r\n\r\n
{
  "type":"request",
  "seq":4,
  "command":"disableTools",
  "arguments":{
                 "tools":["console"]
              }
}
\r\n

Response Packet 'body' values:

<none>

Response Packet status codes:

CODE_OK All of the specified tools are now disabled.
CODE_COMMAND_FAILED At least one of the specified tools was not valid. When this failure occurs none of the specified tools becomes disabled.

Example Response 

Content-Length:809
\r\n\r\n
{
  "type":"response",
  "seq":5,
  "requestSeq":4,
  "command":"disableTools",
  "body":{},
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] enableTools

Enables one or more known tools.
Request Packet 'arguments' values:
"tools" required, array of strings The names of the tools to enable. If any of the values are not valid (eg.- an unknown tool name) then none of the specified tools will become enabled. It is valid to attempt to enable a tool that is already enabled.

Example Request 

Content-Length:84
\r\n\r\n
{
  "type":"request",
  "seq":4,
  "command":"enableTools",
  "arguments":{
                 "tools":["console"]
              }
}
\r\n

Response Packet 'body' values:

<none>

Response Packet status codes:

CODE_OK All of the specified tools are now enabled.
CODE_COMMAND_FAILED At least one of the specified tools was not valid. When this failure occurs none of the specified tools becomes enabled.

Example Response 

Content-Length:809
\r\n\r\n
{
  "type":"response",
  "seq":5,
  "requestSeq":4,
  "command":"enableTools",
  "body":{},
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] evaluate

Evaluates an expression in suspended Javascript.
Request Packet 'arguments' values:
"expression" required, string The Javascript expression to evaluate.
"frameIndex" optional, number The 0-based index of the frame to evaluate the expression in. If this argument is omitted then the evaluation will be done in the first frame.

Example Request 

Content-Length:123
\r\n\r\n
{
  "type":"request",
  "seq":20,
  "command":"evaluate",
  "contextId":"xf0.3::3442767",
  "arguments":{
                 "expression":"2*4-1",
                 "frameIndex":0
              }
}
\r\n

Response Packet 'body' values:

"result" object The result of evaluating the expression. This object will have the form of a Value, according to its type.

Response Packet status codes:

CODE_OK The expression was successfully evaluated.
CODE_COMMAND_FAILED The frameIndex specified a frame that did not exist.
CODE_INVALID_STATE Javascript execution is not currently suspended.

Example Response 

Content-Length:177
\r\n\r\n
{
  "type":"response",
  "seq":21,
  "requestSeq":20,
  "command":"evaluate",
  "contextId":"xf0.3::3442767",
  "body":{
            "result":{
                        "type":"number",
                        "value":7
                     }
         },
  "status":{
              "code":0,
              "running":false
           }
}
\r\n

[edit] frame

[This command has been updated in Crossfire version 0.3a8, please see the migration guide entry for more information.]
Returns a frame when javascript is suspended.
Request Packet 'arguments' values:
"index" required, number The 0-based index of the Frame object to return.
"includeScopes" optional, boolean Specifies whether the frame in the response should include its Scopes. If this argument is omitted then the scopes will be included.

Example Request 

Content-Length:120
\r\n\r\n
{
  "type":"request",
  "seq":33,
  "command":"frame",
  "contextId":"xf0.3::7322351",
  "arguments":{
                 "index":0,
                 "includeScopes":true
              }
}
\r\n

Response Packet 'body' values:

"frame" object The requested Frame object.

Response Packet status codes:

CODE_OK The requested frame was successfully returned.
CODE_COMMAND_FAILED The request's frame index specified an unknown frame.
CODE_INVALID_STATE Javascript execution is not currently suspended.

Example Response 

Content-Length:6764
\r\n\r\n
{
  "type":"response",
  "seq":34,
  "requestSeq":33,
  "command":"frame",
  "contextId":"xf0.3::7322351",
  "body":{
           "frame":{
                      "index":0,
                      "functionName":"onload",
                      "url":"http://www.google.ca//event/seq/1",
                      "locals":{
                                  "this":{
                                            "screen":{"type":"object","handle":42},
                                            "screenLeft":{"type":"number","value":622},
                                            /* ...<snip>... */
                                         }
                                  /* ...<snip>... */
                               },
                      "line":2,
                      "scopes":[{"index":0,"frameIndex":0,"object":{"type":"object","handle":348}}]
                   }
         },
  "status":{
              "code":0,
              "running":false
           }
}
\r\n

[edit] getbreakpoint

This command has been superseded by getBreakpoints.

[edit] getBreakpoints

Returns some or all breakpoints on the server.
Request Packet 'arguments' values:
"handles" optional, array of numbers The handles of the breakpoint objects to return. Invalid handle values (eg.- unknown handles) will not prevent the breakpoints for valid handle values from being returned. If this argument is omitted then all breakpoints are returned.

Example Request 

Content-Length:84
\r\n\r\n
{
  "type":"request",
  "seq":12,
  "command":"getBreakpoints",
  "arguments":{}
}
\r\n

Response Packet 'body' values:

"breakpoints" array of breakpoint objects The requested breakpoints.

Response Packet status codes:

CODE_OK The set of valid requested breakpoint objects was returned.

Example Response 

Content-Length:265
\r\n\r\n
{
  "type":"response",
  "seq":45,
  "requestSeq":44,
  "command":"getBreakpoints",
  "body":{
            "breakpoints":[{
                              "handle":1,
                              "type":"line",
                              "location":{
                                            "line":2,
                                            "url":"http://www.google.ca//event/seq/1"
                                         },
                              "attributes":{
                                              "enabled":true,
                                              "condition":null
                                           }
                          }]
         },
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] getTools

Returns some or all tools registered on the server.
Request Packet 'arguments' values:
"tools" optional, array of strings The string ids of the tool objects to return. Invalid tool values (eg.- unknown tools) will not prevent the tools for valid tool id values from being returned. If this argument is omitted then all tools are returned.

Example Request 

Content-Length:48
\r\n\r\n
{
  "type":"request",
  "seq":10,
  "command":"getTools",
  "arguments":{}
}
\r\n

Response Packet 'body' values:

"tools" array of tool objects The requested tools.

Response Packet status codes:

CODE_OK The set of valid requested tool objects was returned.

Example Response 

Content-Length:809
\r\n\r\n
{
  "type":"response",
  "seq":5,
  "requestSeq":4,
  "command":"getTools",
  "body":{
            "tools":[{
                        "name":"console",
                        "enabled":true,
                        "commands":["setloglevel","setloglimit"],
                        "events":["onConsoleLog","onConsoleDebug","onConsoleInfo","onConsoleWarn","onConsoleError"],
                        "desc":"console is a tool with an unimplemented getDescription() method."
                    }]
         },
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] listContexts

Returns a collection of all current contexts.
Request Packet 'arguments' values:
<none>

Example Request 

Content-Length:51
\r\n\r\n
{
  "type":"request",
  "seq":8,
  "command":"listContexts",
  "arguments":{}
}
\r\n

Response Packet 'body' values:

"contexts" array of Context objects The current contexts.

Response Packet status codes:

CODE_OK The collection of current contexts was successfully returned.

Example Response 

Content-Length:196
\r\n\r\n
{
  "type":"response",
  "command":"listContexts",
  "seq":6,
  "requestSeq":5,
  "body":{
            "contexts":[{"contextId":"xf0.3::5482594","url":"http://www.google.ca/","current":true}]
         },
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] lookup

Returns objects and functions corresponding to specified handles.
Request Packet 'arguments' values:
"handles" required, array of numbers The handles of the Objects/Functions to return. Invalid handle values (eg.- unknown handles) will not prevent the objects/functions for valid handle values from being returned.
"includeSource" optional, boolean Specifies whether the source should be included with returned functions. If this argument is omitted then source will not be included.

Example Request 

Content-Length:257
\r\n\r\n
{
  "type":"request",
  "seq":46,
  "command":"lookup",
  "contextId":"xf0.3::8265385",
  "arguments":{
                 "handles":[10],
                 "includeSource":true
              }
}
\r\n

Response Packet 'body' values:

"values" array of Object and/or Function objects The requested values.

Response Packet status codes:

CODE_OK The set of valid requested objects/functions was returned.

Example Response 

Content-Length:320
\r\n\r\n
{
  "type":"response",
  "seq":10,
  "requestSeq":9,
  "command":"lookup",
  "contextId":"xf0.3::3775561",
  "body":{
            "values": [{
                          "type":"function",
                          "handle":10,
                          "value":{
                                     "constructor":{"type":"function","handle":88},
                                     "proto":{"type":"object","handle":89}
                                  },
                          "source":"function Object() {[native code]}"
                      }]
         },
  "status":{
              "code":0,
              "running":false
           }
}
\r\n

[edit] scope

This command has been superseded by scopes.

[edit] scopes

Returns some or all scopes for a frame when javascript is suspended.
Request Packet 'arguments' values:
"frameIndex" required, number The index of the frame to return the scopes for.
"scopeIndexes" optional, array of numbers The indexes of the scopes to return. Invalid index values will not prevent the scopes for valid index values from being returned. If this argument is omitted then all scopes for the frame will be returned.

Example Request 

Content-Length:106
\r\n\r\n
{
  "type":"request",
  "seq":16,
  "command":"scopes",
  "contextId":"xf0.3::6179868",
  "arguments":{
                 "frameIndex":0
              }
}
\r\n

Response Packet 'body' values:

"scopes" array of Scope objects The requested scopes.

Response Packet status codes:

CODE_OK The set of valid requested scopes was returned.
CODE_COMMAND_FAILED The request's frameIndex specified an invalid frame.
CODE_INVALID_STATE Javascript execution is not currently suspended.

Example Response 

Content-Length:282
\r\n\r\n
{
  "type":"response",
  "seq":17,
  "requestSeq":16,
  "command":"scopes",
  "contextId":"xf0.3::6179868",
  "body":{
            "fromScope":0,
            "toScope":0,
            "totalScopes":1,
            "scopes":[{
                         "index":0,
                         "frameIndex":0,
                         "scope":{"type":"object","handle":19}
                     }]
         },
  "status":{
              "code":0,
              "running":false
           }
}

\r\n

[edit] script

This command has been superseded by scripts.

[edit] scripts

Retrieves some or all known scripts in a context.
Request Packet 'arguments' values:
"urls" optional, array of strings The URLs of the Scripts to return. Invalid values (eg.- unknown URLs) will not prevent the scripts for valid URLs from being returned. If this argument is omitted then all scripts are returned.
"includeSource" optional, boolean Specifies whether the source should be included with returned scripts. If this argument is omitted then source will not be included.

Example Request 

Content-Length:112
\r\n\r\n
{
  "type":"request",
  "seq":52,
  "command":"scripts",
  "contextId":"xf0.3::3788274",
  "arguments":{
                 "includeSource":true
              }
}
\r\n

Response Packet 'body' values:

"scripts" array of Script objects The requested scripts.

Response Packet status codes:

CODE_OK The set of valid requested scripts was returned.

Example Response 

Content-Length:382
\r\n\r\n
{
  "type":"response",
  "seq":32,
  "requestSeq":31,
  "command":"scripts",
  "contextId":"xf0.3::1171142",
  "body":{
           "scripts":[{
                         "url":"http://www.google.ca/",
                         "lineOffset":0,
                         "columnOffset":0,
                         "sourceLength":5,
                         "lineCount":40,
                         "type":"top-level"
                      },                
                      {
                         "url":"http://www.google.ca//event/seq/1",
                         "lineOffset":0,
                         "columnOffset":0,
                         "sourceLength":3,
                         "lineCount":3,
                         "type":"event"
                      }
                     ]
         },
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] setbreakpoint

This command has been superseded by setBreakpoints.

[edit] setBreakpoints

Sets one or more new breakpoints on the server.
Request Packet 'arguments' values:
"breakpoints" required, array of Breakpoint objects without handle values The breakpoints to set on the server.

Example Request 

Content-Length:210
\r\n\r\n
{
  "type":"request",
  "seq":42,
  "command":"setBreakpoints",
  "arguments":{
                 "breakpoints":[{
                                   "type":"line",
                                   "location":{
                                                 "line":2,
                                                 "url":"http://www.google.ca/event/seq/1"
                                              },
                                   "attributes":{
                                                   "enabled":true,
                                                   "condition":null
                                                }
                               }]
              }
}
\r\n

Response Packet 'body' values:

"breakpoints" array of Breakpoint objects Breakpoint objects corresponding to those in the request's breakpoints value, with their handle values set.

Response Packet status codes:

CODE_OK All of the specified breakpoints were valid. Concrete setting of these individual breakpoints will be received in subsequent onToggleBreakpoint events.
CODE_COMMAND_FAILED At least one of the specified breakpoints was not valid. When this failure occurs none of the specified breakpoints are set.

Example Response 

Content-Length:244
\r\n\r\n
{
  "type":"response",
  "seq":44,
  "requestSeq":42,
  "command":"setBreakpoints",
  "body":{
            "breakpoints":[{
                              "handle":1,
                              "type":"line",
                              "location":{
                                            "line":2,
                                            "url":"http://www.google.ca//event/seq/1"
                                         },
                              "attributes":{
                                              "enabled":true
                                           }
                          }]
         },
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] suspend

Tries to suspend running JavaScript as soon as possible.
Request Packet 'arguments' values:
<none>

Example Request 

Content-Length:77
\r\n\r\n
{
  "type":"request",
  "seq":5,
  "command":"suspend",
  "contextId":"xf0.1a::9931113",
  "arguments":{}
}
\r\n

Response Packet 'body' values:

<none>

Response Packet status codes:

CODE_OK An attempt was made to suspend running Javascript as soon as possible. When this suspend occurs an onBreak event will be received.
CODE_INVALID_STATE Javascript execution was already suspended.

Example Response 

Content-Length:105
\r\n\r\n
{
  "type":"response",
  "seq":93,
  "requestSeq":92,
  "command":"suspend",
  "body":{},
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] version

Returns the Crossfire protocol version.
Request Packet 'arguments' values:
<none>

Example Request 

Content-Length:47
\r\n\r\n
{
  "type":"request",
  "seq":10,
  "command":"version",
  "arguments":{}
}
\r\n

Response Packet 'body' values:

"version" string The version string.

Response Packet status codes:

CODE_OK The Crossfire version string was successfully returned.

Example Response 

Content-Length:120
\r\n\r\n
{
  "type":"response",
  "seq":11,
  "requestSeq":10,
  "command":"version",
  "body":{
            "version":"0.3"
         },
  "status":{
              "code":0,
              "running":true
           }
}
\r\n

[edit] Events

[edit] onBreak

Javascript execution has been suspended.
Event Packet 'body' values:
"location" object The current location where execution is suspended. This object consists of a "url" (string) and 1-based "line" (number).
"cause" string The cause of the break. Valid values include "breakpoint" and "suspend".

Example 

Content-Length:156
\r\n\r\n
{
  "type":"event",
  "seq":37,
  "event":"onBreak",
  "contextId":"xf0.3::5159616",
  "body":{
           "location":{"url":"http://www.google.ca//event/seq/1","line":2},
           "cause":{}
         }
}
\r\n

[edit] onContextCreated

A new context has been created on the server.
Event Packet 'body' values:
"contextId" string The id of the new context.
"url" string The URL that the new context was initially navigated to.

Example 

Content-Length:142
\r\n\r\n
{
  "type":"event",
  "seq":5,
  "event":"onContextCreated",
  "body":{
           "url":"http://www.mozilla.com/en-US/firefox/central/",
           "contextId":"xf0.3::6985855"
         }
}
\r\n

[edit] onContextDestroyed

A context has been destroyed on the server.
Event Packet 'body' values:
"contextId" string The id of the destroyed context.

Example 

Content-Length:91
\r\n\r\n
{
  "type":"event",
  "seq":6,
  "event":"onContextDestroyed",
  "body":{
           "contextId":"xf0.3::2075594"
         }
}
\r\n

[edit] onContextLoaded

A context has finished loading its content.
Event Packet 'body' values:
"contextId" string The context's id.
"url" string The URL that has loaded.

Example 

Content-Length:141
\r\n\r\n
{
  "type":"event",
  "seq":7,
  "event":"onContextLoaded",
  "body":{
            "url":"http://www.mozilla.com/en-US/firefox/central/",
            "contextId":"xf0.3::6985855"
         }
}
\r\n

[edit] onContextSelected

The "current" context on the server has changed (eg.- the user has switched between existing tabs in a browser).
Event Packet 'body' values:
"contextId" string The id of the selected context.
"url" string The URL in the selected context.
"oldContextId" string The id of the context switched away from.
"oldUrl" string The URL in the context switched away from.

Example 

Content-Length:181
\r\n\r\n
{
  "type":"event",
  "seq":9,
  "event":"onContextSelected",
  "body":{
            "url":"http://www.google.ca/advanced_search?hl=en",
            "contextId":"xf0.3::9202767",
            "oldUrl":"http://www.ubuntulinux.org/",
            "oldContextId":"xf0.3::9202766"
         }
}
\r\n

[edit] onError

Fired when an error is written to the console or console.error() is used. 
Content-Length:471
\r\n\r\n
{
  "type":"event",
  "event":"onError",
  "contextId":"xf0.3::8821652",
  "seq":136,
  "data":{
           "type":"object",
           "value":{
                     "message":{"type":"string","value":"foo"},
                     "href":{"type":"string","value":"http://www.google.ca/"},
                     "lineNo":{"type":"number","value":0},
                     "source":{"type":"string","value":""},
                     "category":{"type":"string","value":"error"},
                     "context":{"type":"object","handle":24},
                     "trace":{"type":"undefined"},
                     "msgId":{"type":"undefined"},
                     "constructor":{"type":"function","handle":3}
                   }
         }
}

Event Data

data the error information and stack written to the console

[edit] onResume

Javascript execution has been resumed from being suspended.
Event Packet 'body' values:
<none>

Example 

Content-Length:75
\r\n\r\n
{
  "type":"event",
  "seq":11,
  "event":"onResume",
  "contextId":"xf0.3::8127621",
  "body":{}
}
\r\n

[edit] onScript

A new script has been compiled on the server.
Event Packet 'body' values:
"script" script object The new script.

Example 

Content-Length:631
\r\n\r\n
{
  "type":"event",
  "seq":10,
  "event":"onScript",
  "contextId":"xf0.3::2531266",
  "body":{
            "script":{
                        "url":"http://www.google.ca/advanced_search?hl=en",
                        "lineOffset":0,
                        "columnOffset":0,
                        "sourceLength":311,
                        "lineCount":311,
                        "compilationType":"top-level"
                     }
         }
}
\r\n

[edit] onToggleBreakpoint

A breakpoint has been concretely set or removed on the server.
Event Packet 'body' values:
"breakpoint" Breakpoint object The breakpoint.
"set" boolean Indicates whether the breakpoint was set (true) or removed (false).

Example 

Content-Length:255
\r\n\r\n
{
  "type":"event",
  "seq":14,
  "event":"onToggleBreakpoint",
  "contextId":"xf0.3::5524167",
  "body":{
            "breakpoint":{
                            "handle":3,
                            "type":"line",
                            "location":{"line":2,"url":"http://www.google.ca//event/seq/1"},
                            "attributes":{"enabled":true,"condition":null}
                         },
            "set":true
         }
}
\r\n

[edit] Console Tool Events

The console tools will only send any of the following events if they are enabled. By default the console tools are not enabled.

Clients can automatically turn on the console tool via a modified handshake. For more information about the console tool and how to enable and use it see the Console Tool API documentation.

[edit] onConsoleDebug

Fired when debug information is written to the console or console.debug() is used. 
Content-Length:198
\r\n
tool:console
\r\n\r\n
{
  "type":"event",
  "event":"onConsoleDebug",
  "contextId":"xf0.3::8821652",
  "seq":127,
  "data":{
           "type":"object",
           "value":{
                     "0":{"type":"string","value":"foo"},
                     "constructor":{"type":"function","handle":21}
           }
  }
}

Event Data

data the debug information written to the console

[edit] onConsoleInfo

Fired when information is written to the console or console.info() is used. 
Content-Length:197
\r\n
tool:console
\r\n\r\n
{
  "type":"event",
  "event":"onConsoleInfo",
  "contextId":"xf0.3::8821652",
  "seq":144,
  "data":{
           "type":"object",
           "value":{
                     "0":{"type":"string","value":"foo"},
                     "constructor":{"type":"function","handle":21}
           }
  }
}

Event Data

data the log information written to the console

[edit] onConsoleLog

Fired when a log entry is written to the console or console.log() is used. 
Content-Length:196
\r\n
tool:console
\r\n\r\n
{
  "type":"event",
  "event":"onConsoleLog",
  "contextId":"xf0.3::8821652",
  "seq":118,
  "data":{
           "type":"object",
           "value":{
                     "0":{"type":"string","value":"foo"},
                     "constructor":{"type":"function","handle":21}
           }
  }
}

Event Data

data the log information written to the console

[edit] onConsoleWarn

Fired when a warning is written to the console or console.warn() is used. 
Content-Length:197
\r\n
tool:console
\r\n\r\n
{
  "type":"event",
  "event":"onConsoleWarn",
  "contextId":"xf0.3::8821652",
  "seq":152,
  "data":{
           "type":"object",
           "value":{
                     "0":{"type":"string","value":"foo"},
                     "constructor":{"type":"function","handle":21}
           }
  }
}

Event Data

data the warning written to the console

[edit] DOM Tool Events

The DOM tools alert clients to changes in the DOM. By default the DOM tools are not enabled.

Clients can automatically turn on the DOM tool via a modified handshake. For more information about the DOM tool and how to enable and use it see the DOM Tool API documentation.

[edit] onDomMutate 

Content-Length:87
\r\n
tool:dom
\r\n\r\n
{
  "type":"event",
  "event":"onDomMutate",
  "contextId":"xf0.3::8821652",
  "seq":50,
  "data":{}
}

Event Data

[edit] Inspect Tool Events

The Inspector tools notify clients of element inspections in Firebug. By default the Inspector tool is not enabled.

Clients can automatically turn on the inspector tool via a modified handshake. For more information about the inspector tool and how to enable and use it see the Inspector Tool API documentation.

[edit] inspect

Tells Firebug to enter 'inspect' mode on the given node.
The form of the packet is: 
Content-Length:<content_length>
\r\n\r\n
{
  "type":"request",
  "command":"inspect",
  "contextId":<context_id>,
  "seq":<packet_sequence>,
  "arguments":{
                "xpath":<xpath>
                "selector":<selector>
              }
}
\r\n

Arguments

content_length the entire length of the packet content between the curly braces (including the curly braces)
context_id the id of the context this request is targeted for
packet_sequence the packet sequence number
xpath an optional argument specifying the xpath to the node to inspect.
selector an optional argument specifying the selector of the node to inspect

One of xpath or selector must be specified. If both are specified, xpath is used.

Example Request

An example of the request you send: 

Content-Length:128
\r\n\r\n
{
  "type":"request",
  "command":"inspect",
  "contextId":"xf0.3::815372",
  "seq":51,
  "arguments":{
                "xpath":"/html[1]/body[1]/span[1]"
              }
}
\r\n

Example Response

An example of the response you receive: 

Content-Length:307
\r\n\r\n
{
  "type":"response",
  "command":"inspect",
  "seq":53,
  "request_seq":51,
  "body":{
           "xpath":"/html[1]/body[1]/span[1]",
          },
  "running":false,
  "success":true
}


[edit] onInspectNode

Fired when Firebug is in 'Inspect Mode' and DOM elements are inspected. The event contains the path to the DOM element being inspected at the time the even was fired. 
Content-Length:186
\r\n\r\n
{
  "type":"event",
  "event":"onInspectNode",
  "contextId":"xf0.3::7640266",
  "seq":66,
  "data":{
           "node":"/html[1]/body[1]/div[1]/div[4]/div[1]/div[1]/div[2]/div[2]/div[7]/div[1]/span[2]/span[1]"
         }
}

Event Data

node the complete unique path to the element being inspected in the DOM.

[edit] Net Tool Events

The Net tools notify users of information changes in the Net panel. By default the Net tools are not enabled.

Clients can automatically turn on the net tool via a modified handshake. For more information about the net tool and how to enable and use it see the Net Tool API documentation.

[edit] Trace Tool Events

The Trace tool allows additional debug information about what the Crossfire server is doing at any given time to be sent to the remote client. By default the Trace tool is not enabled.

Clients can automatically turn on the trace tool via a modified handshake. For more information about the trace tool and how to enable and use it see the Trace Tool API documentation.

Retrieved from "http://getfirebug.com/wiki/index.php/Crossfire_Protocol_Reference"
Personal tools