chromecast/browser/webview/proto/webview.proto

// Copyright 2019 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// This provides an API to create and control webviews via gRPC.
// Each webview is a separate bidirectional message stream, the client creates
// a new one by sending a WebviewCreate message first. Subsequently, the client
// navigates and injects input as desired and the server will respond with
// event messages whenever page state changes, whether or not in direct response
// to client actions, eg if the renderer crashes.

syntax = "proto3";
option optimize_for = LITE_RUNTIME;
package chromecast.webview;

message AccessibilityTreeInfo {
  string ax_tree_id = 1;
}

// Create a new, empty webview
message WebviewCreateRequest {
  // This identifies the surface that this webview will display into.
  // It should be unique and the same as whatever was set into
  // |aura_surface_set_client_surface_id| on the wayland surface.
  int32 webview_id = 1;
  // This is the cast window ID that will be assigned to the web contents
  // window.
  int32 window_id = 2;
  // True if this webview should exist in an incognito context. It will never
  // persist state.
  bool incognito = 3;
}

message WebviewCreateResponse {
  AccessibilityTreeInfo accessibility_info = 1;
}

message KeyInput {
  // A string value representing the key character or descriptive key name.
  // Values of non-character keys follow the web standard key names:
  // https://www.w3.org/TR/uievents-key/#key-attr-values
  string key_string = 1;
}

message TouchInput {
  float x = 1;
  float y = 2;
  float root_x = 3;
  float root_y = 4;
  int32 pointer_type = 5;
  int32 pointer_id = 6;
  float radius_x = 7;
  float radius_y = 8;
  float force = 9;
  float twist = 10;
  float tilt_x = 11;
  float tilt_y = 12;
  float tangential_pressure = 13;
}

message MouseEvent {
  float x = 1;
  float y = 2;
  float root_x = 3;
  float root_y = 4;
  int32 changed_button_flags = 5;
}

message InputEvent {
  int32 event_type = 1;
  int32 flags = 2;
  // Event timestamps are in monotonically increasing microseconds.
  int64 timestamp = 3;
  KeyInput key = 4;
  TouchInput touch = 5;
  MouseEvent mouse = 6;
}

// Navigate this webview to the provided url.
message NavigateRequest {
  string url = 1;
}

message AsyncPageEvent {
  enum State {
    IDLE = 0;
    LOADING = 1;
    LOADED = 2;
    CLOSED = 3;
    DESTROYED = 4;
    ERROR = 5;
  }
  // This is always set to the current state.
  State current_page_state = 1;
  // These will be set if the event just happened.
  int32 stopped_error_code = 2;
  bool resource_load_failed = 3;
  bool did_first_visually_non_empty_paint = 4;
  string url = 5;
  string stopped_error_description = 6;
}

message StopPageRequest {
  int32 error_code = 1;
}

message EvaluateJavascriptRequest {
  string javascript_blob = 1;
}

message EvaluateJavascriptResponse {
  string json = 1;
}

message AddJavascriptChannelsRequest {
  repeated string channels = 1;
}

message RemoveJavascriptChannelsRequest {
  repeated string channels = 1;
}

message GetCurrentUrlRequest {}

message GetCurrentUrlResponse {
  string url = 1;
}

message CanGoBackRequest {}

message CanGoBackResponse {
  bool can_go_back = 1;
}

message CanGoForwardRequest {}

message CanGoForwardResponse {
  bool can_go_forward = 1;
}

message GoBackRequest {}

message GoForwardRequest {}

message ReloadRequest {}

message ClearCacheRequest {}

message ClearCookiesRequest {}

message ClearCookiesResponse {
  bool had_cookies = 1;
}

message UserAgent {
  oneof type {
    bool is_null = 1;
    string value = 2;
  }
}

message UpdateSettingsRequest {
  bool javascript_enabled = 1;
  bool has_navigation_delegate = 2;
  bool debugging_enabled = 3;
  // A null value means the default user agent should be used.
  // An absent value represents no change to this setting from the last time it
  // was set.
  UserAgent user_agent = 4;
}

message GetTitleRequest {}

message GetTitleResponse {
  string title = 1;
}

message SetAutoMediaPlaybackPolicyRequest {
  bool require_user_gesture = 1;
}

message NavigationRequestEvent {
  reserved 6;  // Was previous_url (b/146374483)

  // The URL the frame is navigating to. This may change during the navigation
  // when encountering a server redirect.
  string url = 1;

  // Whether the navigation is taking place in the main frame or in a subframe.
  // This remains constant over the navigation lifetime.
  bool is_for_main_frame = 2;

  //  False for browser-initiated navigations, including:
  //  * any navigation initiated from the omnibox
  //  * navigations via suggestions in browser UI
  //  * navigations via browser UI: Ctrl-R, refresh/forward/back/home buttons
  //  * using window.history.forward() or window.history.back()
  //  * any other "explicit" URL navigations, e.g. bookmarks
  bool is_renderer_initiated = 3;

  // Whether the navigation happened without changing document. Examples of
  // same document navigations are:
  // * reference fragment navigations
  // * pushState/replaceState
  // * same page history navigation
  bool is_same_document = 4;

  // Whether the navigation was initiated by a user gesture. Note that this
  // will be false for browser-initiated navigations.
  bool has_user_gesture = 5;

  // true if this navigation was initiated by a link click.
  bool was_initiated_by_link_click = 7;

  // Whether the navigation has encountered a server redirect or not.
  bool was_server_redirect = 8;

  // Whether the navigation is done using HTTP POST method. This may change
  // during the navigation (e.g. after encountering a server redirect).
  bool is_post = 9;
}

enum NavigationDecision {
  NAVIGATE = 0;
  PREVENT = 1;
}

message JavascriptChannelMessage {
  string channel = 1;
  string message = 2;
}

// Associate a cast application with a platform view
message AssociateCastAppWindowRequest {
  // This identifies the surface that the cast app will display into.
  // It should be unique from all other platform views.
  // This is the same platform id that is set in webview_id in
  // WebviewCreateRequest
  int32 platform_view_id = 1;
  // This is the id of a cast application.
  int32 app_window_id = 2;
}

message AssociateCastAppWindowResponse {}

message ResizeRequest {
  int32 width = 1;
  int32 height = 2;
}

// Represents the type of a focused text input field.
// Corresponds with blink's public/platform/WebTextInputType.h
// Reference that source for more extended commentary on meaning of each value.
enum TextInputType {
  // Input caret is not in an editable node, no input method shall be used.
  TEXT_INPUT_TYPE_NONE = 0;
  TEXT_INPUT_TYPE_TEXT = 1;
  TEXT_INPUT_TYPE_PASSWORD = 2;
  TEXT_INPUT_TYPE_SEARCH = 3;
  TEXT_INPUT_TYPE_EMAIL = 4;
  TEXT_INPUT_TYPE_NUMBER = 5;
  TEXT_INPUT_TYPE_TELEPHONE = 6;
  TEXT_INPUT_TYPE_URL = 7;
  TEXT_INPUT_TYPE_DATE = 8;
  TEXT_INPUT_TYPE_DATE_TIME = 9;
  TEXT_INPUT_TYPE_DATE_TIME_LOCAL = 10;
  TEXT_INPUT_TYPE_MONTH = 11;
  TEXT_INPUT_TYPE_TIME = 12;
  TEXT_INPUT_TYPE_WEEK = 13;
  TEXT_INPUT_TYPE_TEXT_AREA = 14;
  TEXT_INPUT_TYPE_CONTENT_EDITABLE = 15;
  TEXT_INPUT_TYPE_DATE_TIME_FIELD = 16;

  // Input caret is in an editable node which doesn't support rich editing.
  TEXT_INPUT_TYPE_NULL = 17;
}

// Represents a focus event for an input field within the webview's contents.
message TextInputFocusEvent {
  TextInputType type = 1;

  // Flagged attributes of the focused text input field.
  // Corresponds with those described in blink::WebTextInputFlags in
  // public/platform/WebTextInputType.h
  int32 flags = 2;
}

// Used to represent a space within a rectangle by "shrinking" the rectangle by
// the inset amount on all four sides.
message SetInsetsRequest {
  int32 top = 1;
  int32 left = 2;
  int32 bottom = 3;
  int32 right = 4;
}

message WebviewRequest {
  // Unique identifier for the request. For requests that will have a response,
  // the response id will match the request id.
  // Valid ID values must be greater than 0.
  int64 id = 18;
  oneof type {
    // This must be the first message for CreateWebview.
    WebviewCreateRequest create = 1;
    // No response.
    InputEvent input = 2;
    // Expect page events to follow.
    NavigateRequest navigate = 3;
    // Expect page events to follow.
    StopPageRequest stop_page = 4;
    // Expect async response.
    EvaluateJavascriptRequest evaluate_javascript = 5;
    // No response.
    AddJavascriptChannelsRequest add_javascript_channels = 6;
    // No response.
    RemoveJavascriptChannelsRequest remove_javascript_channels = 7;
    // Expect async response.
    GetCurrentUrlRequest get_current_url = 8;
    // Expect async response.
    CanGoBackRequest can_go_back = 9;
    // Expect async response.
    CanGoForwardRequest can_go_forward = 10;
    // No response.
    GoBackRequest go_back = 11;
    // No response.
    GoForwardRequest go_forward = 12;
    // No response.
    ReloadRequest reload = 13;
    // No response.
    ClearCacheRequest clear_cache = 14;
    // No response.
    UpdateSettingsRequest update_settings = 15;
    // Expect async response.
    GetTitleRequest get_title = 16;
    // No response.
    SetAutoMediaPlaybackPolicyRequest set_auto_media_playback_policy = 17;
    // Response to a navigation request.
    NavigationDecision navigation_decision = 19;
    // This must be the first request for CreateCastAppWindowLink
    AssociateCastAppWindowRequest associate = 20;
    ResizeRequest resize = 21;
    ClearCookiesRequest clear_cookies = 22;
    SetInsetsRequest set_insets = 23;
  }
}

message WebviewResponse {
  // Unique identifier. The value will match that of the request.
  // Responses that do not have an associated request (such as page status
  // event), the ID is meaningless.
  int64 id = 8;
  oneof type {
    WebviewCreateResponse create_response = 1;
    AsyncPageEvent page_event = 2;
    EvaluateJavascriptResponse evaluate_javascript = 3;
    GetCurrentUrlResponse get_current_url = 4;
    CanGoBackResponse can_go_back = 5;
    CanGoForwardResponse can_go_forward = 6;
    GetTitleResponse get_title = 7;
    // Triggered by web navigation events inside the webview.
    NavigationRequestEvent navigation_event = 9;
    // Events sents from JS inside of Webviews to the embedder who added JS
    // channels via AddJavascriptChannelsRequest.
    JavascriptChannelMessage javascript_channel_message = 10;
    ClearCookiesResponse clear_cookies = 11;
    TextInputFocusEvent input_focus_event = 12;
    AssociateCastAppWindowResponse associate = 20;
  }
}

service PlatformViewsService {
  // Creates a webview. See the comment at the top of the file.
  rpc CreateWebview(stream WebviewRequest) returns (stream WebviewResponse);
  // Only AssociateRequest and InputEvent requests are valid.
  rpc CreateCastAppWindowLink(stream WebviewRequest)
      returns (stream WebviewResponse);
}