class Frame

Creates a new view using the specified `view_token`. Caller should pass the other end of

the token to [`fuchsia.ui.gfx/ViewHolderArgs`] to attach the new view to a view tree.

See the description of [`CreateContextParams.service_directory`] for additional services

that must be present when using this method.

Creates a new view using the specified `view_token`. Caller should pass the other end of

the token to [`fuchsia.ui.gfx/ViewHolderArgs`] to attach the new view to a view tree.

`view_ref` can be cloned before passing it to this method, which will allow clients to

track the view.

`view_ref_control` must not have the `ZX_RIGHT_DUPLICATE` set, or view creation will fail

and `view_token` will be closed.

See the description of [`CreateContextParams.service_directory`] for additional services

that must be present when using this method.

Creates a new Flatland view using the specified `view_creation_token` defined under `args`.

Caller should pass the other end of the token to

[`fuchsia.ui.composition/Flatland.CreateViewport`] to attach the new Flatland view to its

graph.

Enables headless rendering of the Frame.

This is used when content depends on layout and/or animation events firing normally.

May only be used on a Context created with [`ContextFeatureFlags.HEADLESS`].

Stops headless rendering of the Frame.

May only be used on a Context created with [`ContextFeatureFlags.HEADLESS`].

Returns a [`fuchsia.media.sessions2/Player`] interface through which media (i.e.

video/audio) playback in the frame may be observed, and/or controlled. Only one

[`fuchsia.media.sessions2/Player`] may be active at a time, for each [`Frame`].

Returns an interface through which the [`Frame`] may be navigated to a desired URL,

reloaded, etc.

- `controller`: An asynchronous interface request for the [`Frame`]'s

[`NavigationController`].

Executes a UTF-8 encoded `script` in the [`Frame`] if the [`Frame`]'s URL has an origin

which matches entries in `origins`.

At least one `origins` entry must be specified. If a wildcard `"*"` is specified in

`origins`, then the script will be evaluated unconditionally.

Returns the result of executing `script`, as a JSON-encoded string.

Note that scripts share the same execution context as the document,

meaning that document may modify variables, classes, or objects set by

the script in arbitrary or unpredictable ways.

If an error occurred, the FrameError will be set to one of these values:

- `BUFFER_NOT_UTF8`: `script` is not UTF-8 encoded.

- `INVALID_ORIGIN`: The [`Frame`]'s current URL does not match any of the values in

`origins` or `origins` is an empty vector.

Variant of [`Frame.ExecuteJavaScript`] which executes the supplied script without returning

a result.

Executes a UTF-8 encoded `script` for every subsequent page load where the [`Frame`]'s URL

has an origin reflected in `origins`. The script is executed early, prior to the execution

of the document's scripts.

Scripts are identified by a client-managed identifier `id`. Any script previously injected

using the same `id` will be replaced.

The order in which multiple bindings are executed is the same as the order in which the

bindings were added. If a script is added which clobbers an existing script of the same

`id`, the previous script's precedence in the injection order will be preserved.

At least one `origins` entry must be specified. If a wildcard `"*"` is specified in

`origins`, then the script will be evaluated unconditionally.

If an error occurred, the [`FrameError`] will be set to one of these values:

- `BUFFER_NOT_UTF8`: `script` is not UTF-8 encoded.

- `INVALID_ORIGIN`: `origins` is an empty vector.

Removes a previously added JavaScript snippet identified by `id`. This is a no-op if there

is no JavaScript snippet identified by `id`.

Posts a message to the frame's onMessage handler.

`target_origin` restricts message delivery to the specified origin. If `target_origin` is

`"*"`, then the message will be sent to the document regardless of its origin.

See the

[HTML spec](https://html.spec.whatwg.org/multipage/web-messaging.html#posting-messages)

section 9.4.3 for more details on how the target origin policy is applied.

If an error occurred, the [`FrameError`] will be set to one of these values:

- `INTERNAL_ERROR`: The WebEngine failed to create a message pipe.

- `BUFFER_NOT_UTF8`: The script in `message`'s `data` property is not UTF-8 encoded.

- `INVALID_ORIGIN`: `origins` is an empty vector.

- `NO_DATA_IN_MESSAGE`: The `data` property is missing in `message`.

Sets the listener for handling page navigation events.

- `listener`: The observer to use. Unregisters any existing listener if null.

Sets the listener for handling page navigation events. The listener will receive the

current navigation state immediately. After that, it's notified whenever the state changes.

- `listener`: The observer to use. Unregisters any existing listener if null.

- `flags`: Flags for optional features that should be enabled for the listener.

If set to a value other than [`ConsoleLogLevel.NONE`], allows web content to log messages

to the [`fuchsia.logger/LogSink`] configured for this [`Frame`], via the

`console` object (e.g. using `debug()`, `log()`, `info()`, `warn()` and

`error()`).

The default value is [`ConsoleLogLevel.NONE`].

As the system log may be persisted, it is recommended that [`ConsoleLogLevel.NONE`] be used

in Incognito and other private browsing modes.

Log lines are written to the [`fuchsia.logger/LogsSink`] configured

for this [`fuchsia.web/Frame`], with severities mapped as follows:

- `debug()`, `log()` and `info()` are logged at [`fuchsia.logger/LogLevelFilter.INFO`]

severity.

- `warn()` is logged at [`fuchsia.logger/LogLevelFilter.WARN`] severity.

- `error()` is logged at [`fuchsia.logger/LogLevelFilter.ERROR`] severity.

Specifies where to emit `console` log output to. By default log output will be routed to a

[`fuchsia.logger/LogSink`] obtained via the [`fuchsia.web/Context`]'s service directory.

- `sink`: The [`fuchsia.logger/LogSink`] to use to emit logs. Passing a `null` handle

resets logging to use the default [`fuchsia.logger/LogSink`].

Enables or disables the processing of the specified `types` of user inputs.

`allow` specifies whether to enable or disable the specified `types`.

All input types are enabled by default.

Sets the listener for handling popup frame opened by web content. If no listener is

present, then any new popup frame will be blocked.

- `listener`: The listener to use. Unregisters any existing listener if null.

Supplies a set of [`UrlRequestRewriteRule`] to apply on every subsequent URL request.

- `rules` are cumulative and applied in order.

- `rules` are only applied on the first URL request in a redirect chain.

- `rules` will be validated before being applied. If `rules` are invalid, the [`Frame`]

will be closed with `ERR_INVALID_ARGS`.

- [`Frame.SetUrlRequestRewriteRules`] must not be called again until its acknowledgement

callback has been processed. If this happens, the [`Frame`] will be closed with

`ERR_BAD_STATE`.

Sets [`fuchsia.media/FrameMediaSettings`] for the frame. The specified parameters are

applied to audio streams that started after this message is processed. Should be called

before the Frame is navigated to content in order to ensure that the settings applied to

all media streams. Due to request pipelining, this means doing so before calling

[`Frame.GetNavigationController()`] and [`NavigationController.LoadUrl()`].

Overrides the dimensions reported to web content. The devicePixelRatio reported to

web content will be adjusted in response to changes in the pixel size of the View,

rather than changing the size reported to the content. Call with null `web_dips` to

remove any prior forced content dimensions.

Sets the permission state for the specified `permission` and `web_origin`. By default, all

permissions are denied.

Sets whether to block all HTMLMediaElements in the frame from fetching and loading media

resources.

May be used, for example, to prevent loading media in frames that are not visible.

While media loading is blocked, elements with `autoplay` set to `true` will not start

playback. The promises returned by calls to `play()` will remain unresolved until loading is

unblocked by a call to this method.

When media loading is unblocked, elements will begin fetching, resource, loading, and

playing as appropriate.

Any elements that have begun fetching or loading media resources for the current source

before media loading was blocked will continue to fetch, load, and start playback as

appropriate. This includes calls to `play()` even after media loading is blocked.

Returns the amount of private (non-shared) physical memory used by the Frame's main

document. The returned size might not reflect the memory usage of embedded iframes.

Sets the navigation policy provider for the [`Frame`]. When set, the [`Frame`] sends

[`NavigationPolicyProvider.EvaluateRequestedNavigation`] when processing navigation

requests. `params` defines when the message is sent. After sending the

`EvaluateRequestedNavigation` message, the [`Frame`] blocks the corresponding navigation

until it receives a response.

Should be called before `GetNavigationController` to ensure that it is applied to all

navigations including the first [`NavigationController.LoadURL`] request.

Sets various settings for how web content should be run in the Frame. May be called at any

time, including after the URL has loaded. Each call changes only the specified fields,

overwriting any prior value.

This method will fail with `ZX_ERR_NOT_SUPPORTED` if any value in [`ContentAreaSettings`]

is not supported by the Frame.

Reset the Frame's [`ContentAreaSettings`] to default values.

Request graceful or immediate teardown of the Frame content and notification of completion

via Frame epitaph.

Graceful teardown allows unload and cleanup tasks in the implementation and web content

(e.g., `unload` event handlers) to run for up to the specified period of time. Immediate

teardown only runs the minimum cleanup tasks in the implementation and does not allow web

content to run event handlers.

* If `timeout` is zero, an immediate teardown is initiated. The channel will close with

`ZX_OK`. This is equivalent to the caller closing the Frame channel.

* If `timeout` is non-zero, a graceful teardown is initiated. The channel will close with

`ZX_OK` if the Frame closes within the specified `timeout` and with `ZX_ERR_TIMED_OUT`

otherwise.

* If `timeout` is not specified, a reasonable implementation-specific timeout is applied.

Subsequent calls to `Close()` will override any previously specified `Close()` timeout.