blob: d7f5d04cac8f562523a96a1e4f695a182c4b70c2 [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.web;
using fuchsia.mem;
/// Interface supplied by the embedder for receiving notifications about navigation events in a
/// [`Frame`].
protocol NavigationEventListener {
/// Called immediately after [`Frame.SetNavigationEventListener`] and every time user-visible
/// navigation state has changed. In the first call, `change` contains the current navigation
/// state (empty before the first navigation request). In every following call, `change` will
/// have values set for all fields that have changed at any time since the previous
/// notification. This means that some fields may have the same value as was previously
/// reported, for example, if they changed to some other value and back again. If a field is
/// unset, then its value has not changed at any time since the previous notification.
/// Implementer must call the acknowledgement callback to receive new navigation events.
OnNavigationStateChanged(resource struct {
change NavigationState;
}) -> ();
protocol NavigationPolicyProvider {
/// Called when the [`Frame`] is processing a navigation request in one of the phase(s)
/// specified in [`NavigationPolicyProviderParams`]. Navigation is paused until the result is
/// received. The returned [`NavigationDecision`] defines how the navigation should proceed.
EvaluateRequestedNavigation(struct {
requested_navigation RequestedNavigation;
}) -> (resource struct {
decision NavigationDecision;
/// Represents the return status of a [`NavigationController`] method.
type NavigationControllerError = strict enum : int32 {
/// The provided URL is invalid.
/// At least one of the provided headers was invalid.
/// Provides methods for controlling and querying the navigation state of a [`Frame`].
protocol NavigationController {
/// Tells the [`Frame`] to navigate to a `url`.
/// - `url`: The address to navigate to.
/// - `params`: Additional parameters that affect how the resource will be loaded (e.g.
/// cookies, HTTP headers, etc.)
/// If an error occurred, the [`NavigationControllerError`] will be set to one of these values:
/// - `INVALID_URL`: The `url` parameter is invalid.
/// - `INVALID_HEADER`: At least one of the headers in [`LoadUrlParams.headers`] is invalid.
LoadUrl(resource struct {
url Url;
params LoadUrlParams;
}) -> (struct {}) error NavigationControllerError;
/// Tells the [`Frame`] to navigate to the previous page in its history, if any.
/// Tells the [`Frame`] to navigate to the next page in its history, if any.
/// Tells the [`Frame`] to stop the current navigation if a navigation is ongoing.
/// Tells the [`Frame`] to reload the current page.
Reload(struct {
type ReloadType;
/// Returns information for the currently visible content regardless of loading state, or an
/// empty entry if no content is being displayed.
@deprecated("Use a NavigationEventListener to receive state changes, instead.")
GetVisibleEntry() -> (resource struct {
entry NavigationState;
/// Additional parameters for modifying the behavior of [`NavigationController.LoadUrl`].
type LoadUrlParams = resource table {
/// Provides a hint to the browser UI about how [`NavigationController.LoadUrl`] was triggered.
1: type LoadUrlReason;
/// The URL that linked to the resource being requested.
2: referrer_url Url;
/// Should be set to true to propagate user activation to the frame. User activation implies
/// that the user is interacting with the web frame. It enables some web features that are not
/// available otherwise. For example, autoplay will work only when this flag is set to true.
3: was_user_activated bool;
/// Custom HTTP headers. RFC7540 does not specify a limit on the number nor
/// size of headers.
4: headers vector<>:MAX;
/// Contains information about the [`Frame`]'s navigation state.
type NavigationState = resource table {
/// The page's URL.
1: url Url;
/// The user-visible page title. While W3C style recommendation is that HTML
/// TITLE tags not exceed 64 characters in length, there is no actual limit.
2: title string:MAX;
/// Indicates whether this was a navigation to an error page.
3: page_type PageType;
/// Indicates if there is a following navigation.
4: can_go_forward bool;
/// Indicates if there is a previous navigation.
5: can_go_back bool;
/// Indicates that the main document's statically declared resources have been loaded.
6: is_main_document_loaded bool;
/// Current favicon for the page. The field is set only when the `FAVICON` flag is set for the
/// `NavigationEventListener` and the favicon has changed.
7: favicon Favicon;
/// Characterizes the type of reload.
type ReloadType = strict enum : uint32 {
/// Reloads the current entry, bypassing the cache for the main resource.
/// Reloads the current entry, bypassing the cache entirely.
/// Characterizes the origin of a [`NavigationController.LoadUrl`] request.
type LoadUrlReason = strict enum : uint32 {
/// Navigation was initiated by the user following a link.
LINK = 0;
/// Navigation was initiated by a user-provided URL.
TYPED = 1;
/// Characterizes the page type in a [`NavigationState`].
type PageType = strict enum {
/// Regular web page.
/// Error page.
ERROR = 1;
/// Unique identifier of a navigation. Can be used to correlate different phases for the
/// same navigation. Guaranteed to be unique for all navigations in the same [`Context`].
alias NavigationId = uint64;
/// Identifies a navigation phase.
type NavigationPhase = strict bits : uint32 {
/// Navigation is being started.
START = 0x1;
/// Navigation was redirected.
/// Navigation response is being processed. At this point navigation hasn't been committed
/// yet, so it is not too late to cancel it.
/// Navigation has failed.
FAIL = 0x8;
/// Used to specify which navigation events should be delegated to [`NavigationPolicyProvider`].
type NavigationPolicyProviderParams = table {
/// Specifies the set of navigation phases in the main frame that should be evaluated.
1: main_frame_phases NavigationPhase;
/// Specifies the set of navigation phases in subframes that should be evaluated.
2: subframe_phases NavigationPhase;
type RequestedNavigation = table {
/// Unique ID of the navigation.
1: id NavigationId;
/// Current navigation phase. Exactly one bit will be set.
2: phase NavigationPhase;
/// Whether the navigation is taking place in the main frame versus in a subframe.
3: is_main_frame bool;
/// Whether the navigation happened without changing the document.
4: is_same_document bool;
/// Whether the navigation is a POST request.
5: is_http_post bool;
/// The current target URL of the navigation. This may change for the same navigation after
/// encountering a server redirect.
6: url Url;
/// Whether the navigation was initiated by a user gesture.
7: has_gesture bool;
/// Whether the navigation has encountered a server redirect or not.
8: was_server_redirect bool;
/// Empty struct used in NavigationDecision for actions that don't hav any arguments.
// TODO:
type NoArgumentsAction = struct {};
/// Navigation action that should be taken in response to a navigation request. Returned from
/// [`NavigationPolicyProvider.EvaluateRequestedNavigation`].
type NavigationDecision = strict resource union {
/// Navigation should proceed normally.
1: proceed NoArgumentsAction;
/// Navigation should be aborted. The frame should stay on the current page.
2: abort NoArgumentsAction;
/// Used to represent a favicon for a page. An empty table (all fields are unset) is used to indicate
/// that the page doesn't have a favicon.
type Favicon = resource table {
/// The image content encoded as an RGBA bitmap with premultiplied alpha channel. The data is
/// densely packed, so the stride is always `4 * width` and the total size is
/// `4 * width * height`.
1: data fuchsia.mem.Buffer;
/// The width of the image.
2: width uint32;
/// The height of the image.
3: height uint32;