components/web_view/public/interfaces/frame.mojom

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 module web_view.mojom;
   6
   7 import "network/public/interfaces/url_loader.mojom";
   8
   9 // This files defines the interfaces and structures used for frames.
  10 //
  11 // When a client in the frame tree is connected to by way of the ViewManager a
  12 // FrameClient is obtained (from the ServiceProvider interface request passed
  13 // in ViewManager::OnEmbed()). The FrameClient is told the frame tree (by way
  14 // of OnConnection()), which allows the client to use other frames in the tree
  15 // (assuming the client has the appropriate permissions).
  16 //
  17 // frame_ids are the same as views ids. This means that when a client creates
  18 // a new view to be part of the frame tree it immediately knows the id to use
  19 // for Frame calls.
  20 //
  21 // The server provides an id that may be used to identify the state of the
  22 // tree. The change id is an integer that is incremented every time the
  23 // structure of the tree changes. The change id is not used by the server; the
  24 // server only updates the change id and notifies clients of the new id (by
  25 // way of structure change functions such as OnFrameAdded()).
  26
  27 // Expresses a preference for where a navigation should occur.
  28 enum NavigationTargetType {
  29   // No preference.
  30   NO_PREFERENCE,
  31
  32   // In the specified frame.
  33   EXISTING_FRAME,
  34
  35   // In a new frame.
  36   NEW_FRAME,
  37 };
  38
  39 // Provides information about a frame.
  40 struct FrameData {
  41   // 0 if the frame has no parent (its the root).
  42   uint32 parent_id;
  43   uint32 frame_id;
  44
  45   // A map of the properties supplied by the client. The server does not
  46   // intepret these values in anyway, the meaning and usage is left up to
  47   // clients.
  48   map<string, array<uint8>>? client_properties;
  49 };
  50
  51 // TODO(sky): decide which bits of this make sense for all frames, and move the
  52 // html specific parts into properties.
  53 struct HTMLMessageEvent {
  54   // The serialized script value.
  55   array<uint8>? data;
  56
  57   // The origin of the source frame.
  58   string source_origin;
  59
  60   // The origin for the message's target.
  61   string? target_origin;
  62
  63   // TODO(sky): these two are not implemented. Figure out what they should be.
  64   // Information about the MessagePorts this message contains.
  65   // IPC_STRUCT_MEMBER(std::vector<content::TransferredMessagePort>, message_ports)
  66   // IPC_STRUCT_MEMBER(std::vector<int>, new_routing_ids)
  67 };
  68
  69 interface Frame {
  70   // Requests the server to message the specified frame with |event|. If the
  71   // operation is allowed OnPostMessageEvent() is called on the appropriate
  72   // FrameClient.
  73   PostMessageEventToFrame(uint32 target_frame_id, HTMLMessageEvent event);
  74
  75   // Notifies the server that the loading state and progress changed.
  76   LoadingStateChanged(bool loading, double progress);
  77
  78   // Called when the title becomes available or changes.
  79   TitleChanged(string? title);
  80
  81   // Called when the response body has been received.
  82   DidCommitProvisionalLoad();
  83
  84   // Sets the value of the specified client property, notifying clients if the
  85   // value changed. If |value| is null the property is removed.
  86   SetClientProperty(string name, array<uint8>? value);
  87
  88   // Called when the client creates a new frame. |frame_id| corresponds to
  89   // the id of the view hosting the frame, and |parent_id| the id of the
  90   // parent. See FrameData::client_properties for details of
  91   // |client_properties|.
  92   //
  93   // Note that the FrameClient still gets an OnConnect(), but the only thing of
  94   // interest is the callback.
  95   OnCreatedFrame(Frame& frame_request,
  96                  FrameClient client,
  97                  uint32 frame_id,
  98                  map<string, array<uint8>> client_properties);
  99
 100   // Requests a navigation. If |target_TYPE| is |EXISTING_FRAME|, then
 101   // |target_frame_id| identifies the frame to navigate in. Otherwise
 102   // |target_frame_id| is unused.
 103   RequestNavigate(NavigationTargetType target_type,
 104                   uint32 target_frame_id,
 105                   mojo.URLRequest request);
 106
 107   // The frame navigated locally, for example, pushState() navigations in an
 108   // HTML application.
 109   DidNavigateLocally(string url);
 110
 111   // Dispatches a load event to the parent of the frame.
 112   DispatchLoadEventToParent();
 113 };
 114
 115 enum ViewConnectType {
 116   // Indicates the app is already a ViewTreeClient and the existing view should
 117   // be used. In this case the app is not asked for a new ViewTreeClient.
 118   USE_EXISTING,
 119
 120   // Indicates a new ViewTreeClient is obtained and the View provided to
 121   // OnEmbed() should be used.
 122   USE_NEW
 123 };
 124
 125 interface FrameClient {
 126   // Called once per client. |frame_data| gives the contents of the tree.
 127   // |view_id| is the id of the view the FrameClient should render to. If a
 128   // ViewTreeClient is asked for then |view_id| is the same id as that of the
 129   // View supplied to ViewTreeClient::OnEmbed().
 130   OnConnect(Frame? frame,
 131             uint32 change_id,
 132             uint32 view_id,
 133             ViewConnectType view_connect_type,
 134             array<FrameData>? frame_data) => ();
 135
 136   // Called when a new frame is added to the tree.
 137   OnFrameAdded(uint32 change_id, FrameData frame_data);
 138
 139   // Called when a frame is removed from the tree.
 140   OnFrameRemoved(uint32 change_id, uint32 frame_id);
 141
 142   // Called when a client property changes.
 143   OnFrameClientPropertyChanged(uint32 frame_id,
 144                                string name,
 145                                array<uint8>? new_value);
 146
 147   // See description in PostMessageEventToFrame().
 148   OnPostMessageEvent(uint32 source_frame_id,
 149                      uint32 target_frame_id,
 150                      HTMLMessageEvent event);
 151
 152   // Called prior to starting a new navigation. This is only called on the
 153   // FrameClient that is rendering to the frame, and only when another content
 154   // handler is going to start handling the rendering.
 155   OnWillNavigate();
 156
 157   // Called to notify that |frame_id|'s loading state has changed. This is only
 158   // called on the FrameClient rendering the parent of |frame_id|.
 159   OnFrameLoadingStateChanged(uint32 frame_id, bool loading);
 160
 161   // Called to dispatch a load event of |frame_id| in its parent. This is only
 162   // called on the FrameClient rendering the parent of |frame_id|.
 163   OnDispatchFrameLoadEvent(uint32 frame_id);
 164 };