script.disown command

Syntax

/* With required parameters */
{
  "method": "script.disown",
  "params": {
    "handles": ["f1e2d3c4-b5a6-4978-8b9c-0d1e2f3a4b5c"],
    "target": {
      "realm": "7c37f4c0-abcd-1234-ef56-789012345678"
    }
  }
}

/* With required and optional parameters */
{
  "method": "script.disown",
  "params": {
    "handles": ["f1e2d3c4-b5a6-4978-8b9c-0d1e2f3a4b5c"],
    "target": {
      "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
      "sandbox": "myAutomationSandbox"
    }
  }
}

Parameters

The params field contains:

handles

An array of strings that specifies the handles to release. Any specified handle not found in the target realm is ignored. Handles are returned in a handle field when a command such as script.evaluate is sent with resultOwnership set to root.

target

An object that specifies the realm that owns the specified handles. The object must contain either a context field or a realm field:

context

A string that contains the ID of the context whose active document provides the realm that owns the handles. Context IDs are returned by commands such as browsingContext.getTree.

realm

A string that contains the ID of the realm that owns the handles. Realm IDs are returned by the script.getRealms command.

sandbox Optional

A string that contains the name of the sandbox realm that owns the handles. For a non-empty name, the browser creates a sandbox realm with that name in the specified context if one doesn't already exist. For an empty name (""), handles are released from the realm of the active document instead. This field is available only when the target object contains a context field.

Return value

The result field in the response is an empty object ({}).

Errors

invalid argument

Thrown if a required parameter is missing or has an invalid type.

no such frame

Thrown in any of the following cases:

• No context with the specified context ID is found.
• No realm with the specified realm ID is found.

Description

A handle is a string identifier you can use to refer to an object in subsequent script module commands, for example, to pass the object as an argument to script.callFunction. You can use it only in the realm in which it was created. After a handle is released, you can no longer use it in other script commands. The object isn't necessarily garbage collected. Other handles or references from the page's own scripts can keep the object alive.

The browser automatically releases handles when their realm is destroyed (see the script.realmDestroyed event). You can use script.disown to release handles you no longer need before the realm is destroyed.

Examples

Releasing a handle using a context ID

Assume you have a WebDriver BiDi connection and an active session. You get an open tab's context ID by using browsingContext.getTree.

Suppose the tab's page contains a button, and you evaluate the expression document.querySelector('button') by using script.evaluate. In that command, you pass the context ID in the target parameter and set the resultOwnership parameter to root. The expression returns the button element, a DOM node that supports a handle. With resultOwnership set to root, the browser includes a handle for that element in the response.

When you no longer need the handle for this element, send the following message to release it. Use the tab's context ID and the returned handle, without navigating or reloading the page between the two commands:

{
  "id": 5,
  "method": "script.disown",
  "params": {
    "handles": ["f1e2d3c4-b5a6-4978-8b9c-0d1e2f3a4b5c"],
    "target": {
      "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f"
    }
  }
}

The browser responds with an empty result object:

{
  "id": 5,
  "type": "success",
  "result": {}
}

Releasing multiple handles using a realm ID

Using the same connection and session as in the first example, suppose you have two handles for objects in the same realm. Send the following message to release both handles, using the ID of that realm in target:

{
  "id": 6,
  "method": "script.disown",
  "params": {
    "handles": [
      "a9b8c7d6-e5f4-4321-9a8b-7c6d5e4f3a2b",
      "b2c3d4e5-f6a7-4b89-9c0d-1e2f3a4b5c6d"
    ],
    "target": {
      "realm": "7c37f4c0-abcd-1234-ef56-789012345678"
    }
  }
}

The browser responds with an empty result object:

{
  "id": 6,
  "type": "success",
  "result": {}
}

Specifications

Browser compatibility

See also

• script.evaluate command
• script.callFunction command
• script.getRealms command
• script.realmDestroyed event