Skip to content

Commands

Jump to bottom
mrennie edited this page Nov 2, 2012 · 21 revisions

All of the commands that Crossfire supports are JSON-formatted objects. Each command has special arguments that they support and differing formations of responses. All commands follow the general form of request and response packets.

The complete description of each command, their arguments, responses and examples can be found below.

Contents

backtrace

Returns a backtrace (stacktrace) of frames when JavaScript is suspended.

Request packet arguments values

fromFrame number, optional
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 number, optional
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 boolean, optional
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

changeBreakpoint

This command has been updated in Crossfire version 0.3a11, please see the migration guide entry for more information.

Changes the attributes of a breakpoint.

Request packet arguments values

handle number, required
The handle of the breakpoint to change.
attributes object, required
The attributes to set or update on the breakpoints.

Example Request

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

Response packet body values

none
There is no body defined for the response

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
The specified breakpoint handle or some of the attributes were 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 breakpoint attributes are changed.

Example Response

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

continue

Resumes execution of JavaScript that is suspended.

Request packet arguments values

stepAction string, optional {in | next | out}
Specifies the type of resume. Valid values are innext (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

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

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 string, optional
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 string, required
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

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

deleteBreakpoints

Deletes a set of breakpoints.

Request packet arguments values

handles array of numbers, required
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

disableTools

Disables one or more known tools.

Request packet arguments values

tools array of string, required
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

enableTools

Enables one or more known tools.

Request packet arguments values

tools array of strings, required
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

evaluate

Evaluates an expression in suspended JavaScript.

Request packet arguments values

expression string, required
The JavaScript expression to evaluate.
frameIndex number, optional
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

frame

Returns a frame when JavaScript is suspended.

Request packet arguments values

index number, required
The 0-based index of the [Frame](#Frame) object to return.
boolean, optional
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

getBreakpoints

Returns all of the breakpoints currently registered.

Request packet arguments values

handles array of number, optional
The handles of the [breakpoint](#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](#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

getTools

Returns all the tools currently registered in Crossfire

Request packet arguments values

tools array or strings, optional
The string ids of the [tool](#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

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

lookup

Returns objects and/or functions corresponding to specified handles.

Request packet arguments values

handles array of numbers, required
The handles of the [Objects](#Object)/[Functions](#Function) to return. Invalid handle values (eg.- unknown handles) will not prevent the objects/functions for valid handle values from being returned.
includeSource boolean, optional
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 objects and/or function objects
The reported values.

Response packet status codes

CODE_OK
If the object or function 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

scopes

Returns some or all scopes for a frame when JavaScript is suspended.

Request packet arguments values

frameIndex number, required
The index of the frame to return the scopes for.
scopeIndexes array of numbers, optional
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

scripts

Retrieves some or all known scripts in a context.

Request packet arguments values

urls array of strings, optional
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 boolean, optional
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

setBreakpoints

Sets one or more new breakpoints in Crossfire

Request packet arguments values

breakpoints array of breakpoint objects (without handle values), required
The breakpoints to set in Crossfire.

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](#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

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

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":{
              "ode":0,
              "running":true
           }
}
\r\n
Clone this wiki locally