blob: e257f61e8b3364b0c051ddf6d1716d76fdc3d5ef [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.net.http;
/// Interface supplied by the embedder for receiving notifications about navigation events in a
/// [`Frame`].
protocol NavigationEventListener {
/// Called when user-visible navigation state has changed since [`Frame`] creation or the last
/// acknowledgement callback, whichever occurred last. `change` will contain all the
/// differences in navigation state since the last acknowledgement. Any unchanged properties
/// will be left unset in `change`.
///
/// Implementer must call the acknowledgement callback to receive new navigation events.
OnNavigationStateChanged(NavigationState change) -> ();
};
/// Represents the return status of a [`NavigationController`] method.
enum NavigationControllerError : int32 {
/// The provided URL is invalid.
INVALID_URL = 1;
/// At least one of the provided headers was invalid.
INVALID_HEADER = 2;
};
/// 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 occured, 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(Url url, LoadUrlParams params)
-> () error NavigationControllerError;
/// Tells the [`Frame`] to navigate to the previous page in its history, if any.
GoBack();
/// Tells the [`Frame`] to navigate to the next page in its history, if any.
GoForward();
/// Tells the [`Frame`] to stop the current navigation if a navigation is ongoing.
Stop();
/// Tells the [`Frame`] to reload the current page.
Reload(ReloadType type);
/// Returns information for the currently visible content regardless of loading state, or an
/// empty entry if no content is being displayed.
GetVisibleEntry() -> (NavigationState entry);
};
/// Additional parameters for modifying the behavior of [`NavigationController.LoadUrl`].
resource table LoadUrlParams {
/// Provides a hint to the browser UI about how [`NavigationController.LoadUrl`] was triggered.
1: LoadUrlReason type;
/// The URL that linked to the resource being requested.
2: Url referrer_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: bool was_user_activated;
/// Custom HTTP headers. RFC7540 does not specify a limit on the number nor
/// size of headers.
4: vector<fuchsia.net.http.Header>:MAX headers;
};
/// Contains information about the [`Frame`]'s navigation state.
resource table NavigationState {
/// 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: string:MAX title;
/// Indicates whether this was a navigation to an error page.
3: PageType page_type;
/// Indicates if there is a following navigation.
4: bool can_go_forward;
/// Indicates if there is a previous navigation.
5: bool can_go_back;
/// Indicates that the main document's statically declared resources have been loaded.
6: bool is_main_document_loaded;
};
/// Characterizes the type of reload.
enum ReloadType : uint32 {
/// Reloads the current entry, bypassing the cache for the main resource.
PARTIAL_CACHE = 0;
/// Reloads the current entry, bypassing the cache entirely.
NO_CACHE = 1;
};
/// Characterizes the origin of a [`NavigationController.LoadUrl`] request.
enum LoadUrlReason : 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`].
enum PageType {
/// Regular web page.
NORMAL = 0;
/// Error page.
ERROR = 1;
};