Ecmascript.1.0

Provides access to functionality in the ECMAScript engine. Basic usage is to query the runtime list first, all commands require a runtime ID to work with.

All IDs in this service will be invalid once the service is disabled.

Note: For debugging of ECMAScript see the EcmascriptDebugger service.

Eval

Evaluate a piece of ECMAScript in the global scope. For instance to fetch information on the window object, one can do::

Eval(runtimeID=1, scriptData="window")

EvalResult.value.object will be set, note however that this will not include properties on the return object to conserve the amount of data that needs to be sent. To get properties use ExamineObjects().

command Eval(EvalArg)

// command Eval(EvalArg) returns (EvalResult) = 2;
```
required uint32 runtimeID = 1;
```
ID of runtime to execute script in.
```
required string scriptData = 2;
```
The script data to execute, this can either be an expression or a statement. The semi-colon can be omitted.

Eval() will return the value of the last expression that is evaluated.

Some examples::
"2 + 2" "window" // returns the window object "x = 5; x*x" "my_function()"
```
 repeated Variable variableList = 3;
```
A list of objects to place in the execution environment when evaluating scriptData.

Each object is assigned to variable specified in Variable.name.
```
{
```
- A variable to assign in the execution environment before evaluating the script.
- ```
required string name = 1;
```
  Name of variable to create.
- ```
required uint32 objectID = 2;
```
  ID of object to retrieve, the object is assigned to the specified name.
```
}
```

returns (EvalResult)

Result of a script execution.

 required Status status = 1;

Evaluation status, a successful evaluation returns SUCCESS.

```
SUCCESS = 1;
```
```
FAILURE = 2;
```
```
EXCEPTION = 3;
```
```
NO_MEMORY = 4;
```
```
CANCELLED = 5;
```

```
 required Value value = 2;
```
The result of the evaluated script.

If execution failed (status != SUCCESS) then this will contain the undefined value.
```
{
```
- Represents an ECMAScript value, a value is either one of the primitives like string or boolean or an object.
- ```
 optional Type type = 1;
```
  The type of value.
  
  Booleans are encoded as either TRUE or FALSE to shorten the number fields in use.
```
{
```
  - UNDEFINED = 0;
    
    The undefined type, returned when no value was found or "undefined" was referenced.
  - NULL = 1;
    
    A null value.
  - TRUE = 2;
    
    Boolean value true.
  - FALSE = 3;
    
    Boolean value false.
  - NAN = 4;
    
    NaN value which cannot be exported to JSON directly. Should be treated like a number.
    
    ECMAScript users should use this code to get the value natively::
    parseFloat("NaN")
  - PLUS_INFINITY = 5;
    
    Plus infinity value which cannot be export to JSON directly. Should be treated like a number.
    
    ECMAScript users should use this code to get the value natively::
    parseFloat("Infinity")
  - MINUS_INFINITY = 6;
    
    Minus infinity value which cannot be export to JSON directly. Should be treated like a number.
    
    ECMAScript users should use this code to get the value natively::
    parseFloat("-Infinity")
  - NUMBER = 7;
    
    A number, use the field 'number' for the actual value.
  - STRING = 8;
    
    A string, use the field 'str' for the actual string data.
  - OBJECT = 9;
    
    An object, the field 'object' contains object details.
```
}
```
- ```
optional double number = 2;
```
  The numeric value, set if type = NUMBER.
- ```
optional string str = 3;
```
  The string, set if type = STRING.
- ```
 optional Object object = 4;
```
  Object information, set if type = OBJECT.
```
{
```
  - An Object is any non-primitive value in ECMAScript. Functions and arrays, for instance, are also Objects.
  - required uint32 objectID = 1;
    
    The unique ID of the object, valid until the object is garbage collected or the service is disabled.
    
    Is an integer from 1 and up.
  - required bool isCallable = 2;
    
    true if the object can be called, this is typically functions but other objects are also possible.
  - required ObjectType type = 3;
    
    The type of object, either a plain object or a function.
    
    {
    
    OBJECT = 1;
    
    FUNCTION = 2;
    
    }
  - optional uint32 prototypeID = 4;
    
    The ID of the prototype for this object if it has a prototype. A prototype is just another object and can be examined with ExamineObjects().
  - optional string className = 5;
    
    The name of the class used to create this object. Examples::
    "Object" "Array" "Function" "HTMLHtmlElement"
  - optional string functionName = 6;
    
    The name of the function, only set if type = FUNCTION. If the function is anonymous, then a suitable alias may be assigned based on context, if possible. For instance::
    foo.bar = function(){}
    Would get the functionName 'bar'.
  - repeated Property propertyList = 7;
    
    A list of properties available on the object.
    
    Is omitted in some cases when a full property list (can be huge) is not desirable.
    
    {
    
    required string name = 1;
    
    required Value value = 2;
    
    }
```
}
```
```
}
```

= 2;

ExamineObjects

Request additional information about an object, such as its prototype or its properties.

For instance to get more information on the window object, one can do::

ExamineObjects(runtimeID=1, objectList=[2], examinePrototypes=true)

Here the object ID was the ID previously returned from an Eval() call.

command ExamineObjects(ExamineObjectsArg)

// command ExamineObjects(ExamineObjectsArg) returns (ObjectList) = 3;
```
required uint32 runtimeID = 1;
```
ID of runtime to examine object in.
```
repeated uint32 objectIDList = 2;
```
List of object IDs to examine.
```
optional bool examinePrototypes = 3 [default = false];
```
If true then each examined object will also include the prototype chain.

returns (ObjectList)

Contains a list of prototype chains from the ExamineObject() command.
```
 repeated PrototypeChain prototypeList = 1;
```
```
{
```
- A list of prototypes for the examined object, the first entry [0] is the examined object while the rest are the object info for each prototype in the chain.
  
  If prototype were not examined the list contains only one entry.
- ```
 repeated Object objectList = 1;
```
```
{
```
  - An Object is any non-primitive value in ECMAScript. Functions and arrays, for instance, are also Objects.
  - required uint32 objectID = 1;
    
    The unique ID of the object, valid until the object is garbage collected or the service is disabled.
    
    Is an integer from 1 and up.
  - required bool isCallable = 2;
    
    true if the object can be called, this is typically functions but other objects are also possible.
  - required ObjectType type = 3;
    
    The type of object, either a plain object or a function.
    
    {
    
    OBJECT = 1;
    
    FUNCTION = 2;
    
    }
  - optional uint32 prototypeID = 4;
    
    The ID of the prototype for this object if it has a prototype. A prototype is just another object and can be examined with ExamineObjects().
  - optional string className = 5;
    
    The name of the class used to create this object. Examples::
    "Object" "Array" "Function" "HTMLHtmlElement"
  - optional string functionName = 6;
    
    The name of the function, only set if type = FUNCTION. If the function is anonymous, then a suitable alias may be assigned based on context, if possible. For instance::
    foo.bar = function(){}
    Would get the functionName 'bar'.
  - repeated Property propertyList = 7;
    
    A list of properties available on the object.
    
    Is omitted in some cases when a full property list (can be huge) is not desirable.
    
    {
    
    required string name = 1;
    
    required Value value = 2;
    
    {
    
    Represents an ECMAScript value, a value is either one of the primitives like string or boolean or an object.
    
    optional Type type = 1;
    
    The type of value.
    
    Booleans are encoded as either TRUE or FALSE to shorten the number fields in use.
    
    {
    
    UNDEFINED = 0;
    
    The undefined type, returned when no value was found or "undefined" was referenced.
    
    NULL = 1;
    
    A null value.
    
    TRUE = 2;
    
    Boolean value true.
    
    FALSE = 3;
    
    Boolean value false.
    
    NAN = 4;
    
    NaN value which cannot be exported to JSON directly. Should be treated like a number.
    
    ECMAScript users should use this code to get the value natively::
    parseFloat("NaN")
    
    PLUS_INFINITY = 5;
    
    Plus infinity value which cannot be export to JSON directly. Should be treated like a number.
    
    ECMAScript users should use this code to get the value natively::
    parseFloat("Infinity")
    
    MINUS_INFINITY = 6;
    
    Minus infinity value which cannot be export to JSON directly. Should be treated like a number.
    
    ECMAScript users should use this code to get the value natively::
    parseFloat("-Infinity")
    
    NUMBER = 7;
    
    A number, use the field 'number' for the actual value.
    
    STRING = 8;
    
    A string, use the field 'str' for the actual string data.
    
    OBJECT = 9;
    
    An object, the field 'object' contains object details.
    
    }
    
    optional double number = 2;
    
    The numeric value, set if type = NUMBER.
    
    optional string str = 3;
    
    The string, set if type = STRING.
    
    optional Object object = 4;
    
    Object information, set if type = OBJECT.
    
    }
    
    }
```
}
```
```
}
```

= 3;

ListRuntimes

List all runtimes (in all Windows). For instance to fetch all runtimes of all windows one can do::

ListRuntimes(runtimeList=[], create=true)

If you already have a runtime ID you can pass it in runtimeList to get get back information, e.g.::

ListRuntimes(runtimeList=[1])

command ListRuntimes(ListRuntimesArg)

// command ListRuntimes(ListRuntimesArg) returns (RuntimeList) = 1;
```
repeated uint32 runtimeIDList = 1;
```
If non-empty, only information about the specified runtime(s) will be received.
```
optional bool create = 2;
```
If true, runtimes will be created for documents which would otherwise not require them.

returns (RuntimeList)

```
 repeated Runtime runtimeList = 1;
```
```
{
```
- A runtime is an ECMAScript execution environment.
- ```
required uint32 runtimeID = 1;
```
  A unique ID for this runtime, persists through the entire session or until the runtime is destroyed.
  
  Is an integer from 1 and up.
- ```
required string htmlFramePath = 2;
```
  The frame path in the window, for instance "_top" means the top-most frame of a window.
  
  Other examples are::
  "_top/[1]" "_top/[1]/[1]"
- ```
required uint32 windowID = 3;
```
  The ID this window belongs to.
  
  Multiple frames in a window will be reported as multiple runtimes and they will all share the same windowID.
- ```
required uint32 objectID = 4;
```
  The global object associated with this runtime.
- ```
required string uri = 5;
```
  The URI of the resource loaded in the runtime. This can be a normal URI (HTTP etc.) or a special interal URI like "opera:blank" or "opera:debug".
```
}
```

= 1;

ReleaseObjects

Release protected ECMAScript objects. This will just make them garbage collectible. Released objects are not necessarily freed immediately.

Calling ReleaseObjects with an empty list causes all objects to be released. Otherwise, only the specified objects will be released. Attempting to release a non-existent object has no effect, and will fail silently.

Releasing objects invalidates associated object IDs immediately.

command ReleaseObjects(ReleaseObjectsArg)

List of objects to release.
```
repeated uint32 objectIDList = 1;
```

returns (Default)

= 4;

OnReadyStateChanged

Occurs when certain 'milestones' of page-loading have been reached. See message 'ReadyStateChange' for details.

event OnReadyStateChanged returns (ReadyStateChange)

```
required uint32 runtimeID = 1;
```
```
 required State state = 2;
```
```
{
```
- ```
DOM_ENVIRONMENT_CREATED = 1;
```
  Occurs immediately after the DOM environment is created for a document.
- ```
DOM_CONTENT_LOADED = 2;
```
  This state indicates that the HTML tree is done (for now). The event happens immediately after the DOMContentLoaded event fires on the window object. Useful for figuring out when we can inspect the DOM.
- ```
AFTER_ONLOAD = 3;
```
  Occurs after onload is finished, and after external resources are loaded. When this event is observed, it should be safe to take a screenshot.
```
}
```

= 5;

Ecmascript1.0

Commands

Events

Eval

ExamineObjects

ListRuntimes

ReleaseObjects

OnReadyStateChanged