components/web_view/public/interfaces/frame_tree.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;
   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 // FrameTreeClient is obtained (from the ServiceProvider interface request
  13 // passed in ViewManager::OnEmbed()). The FrameTreeClient is told the frame
  14 // tree (by way of OnConnection()), which allows the client to use other
  15 // frames in the tree (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 FrameTreeServer 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 FrameTreeServer {
  70   // Requests the server to message the specified frame with |event|. If the
  71   // operation is allowed OnPostMessageEvent() is called on the appropriate
  72   // FrameTreeClient.
  73   PostMessageEventToFrame(uint32 source_frame_id,
  74                           uint32 target_frame_id,
  75                           HTMLMessageEvent event);
  76
  77   // Notifies the server that a load has started or stopped in this frame.
  78   // When loading is started, progress is reset to 0, but when loading is
  79   // stopped progress may not have reached 1.0.
  80   LoadingStarted(uint32 frame_id);
  81   LoadingStopped(uint32 frame_id);
  82
  83   // Called when the progress for this frame changes. Will only be called while
  84   // a load is in progress.
  85   ProgressChanged(uint32 frame_id, double progress);
  86
  87   // Called when the title becomes available or changes.
  88   TitleChanged(uint32 frame_id, string? title);
  89
  90   // Sets the value of the specified client property, notifying clients if the
  91   // value changed. If |value| is null the property is removed.
  92   SetClientProperty(uint32 frame_id,
  93                     string name,
  94                     array<uint8>? value);
  95
  96   // Called when the client creates a new frame. |frame_id| corresponds to
  97   // the id of the view hosting the frame, and |parent_id| the id of the
  98   // parent. See FrameData::client_properties for details of
  99   // |client_properties|.
 100   OnCreatedFrame(uint32 parent_id,
 101                  uint32 frame_id,
 102                  map<string, array<uint8>> client_properties);
 103
 104   // Requests a navigation. If |target_TYPE| is |EXISTING_FRAME|, then
 105   // |target_frame_id| identifies the frame to navigate in. Otherwise
 106   // |target_frame_id| is unused.
 107   RequestNavigate(NavigationTargetType target_type,
 108                   uint32 target_frame_id,
 109                   mojo.URLRequest request);
 110
 111   // The frame navigated locally, for example, pushState() navigations in an
 112   // HTML application.
 113   DidNavigateLocally(uint32 frame_id, string url);
 114 };
 115
 116 enum ViewConnectType {
 117   // Indicates the app is already a ViewTreeClient and the existing view should
 118   // be used. In this case the app is not asked for a new ViewTreeClient.
 119   USE_EXISTING,
 120
 121   // Indicates a new ViewTreeClient is obtained and the View provided to
 122   // OnEmbed() should be used.
 123   USE_NEW
 124 };
 125
 126 interface FrameTreeClient {
 127   // Called once per client. |frame_data| gives the contents of the tree.
 128   // |view_id| is the id of the view the FrameTreeClient should render to. If
 129   // a ViewTreeClient is asked for then |view_id| is the same id as that of the
 130   // View supplied to ViewTreeClient::OnEmbed().
 131   OnConnect(FrameTreeServer server,
 132             uint32 change_id,
 133             uint32 view_id,
 134             ViewConnectType view_connect_type,
 135             array<FrameData> frame_data) => ();
 136
 137   // Called when a new frame is added to the tree.
 138   OnFrameAdded(uint32 change_id, FrameData frame_data);
 139
 140   // Called when a frame is removed from the tree.
 141   OnFrameRemoved(uint32 change_id, uint32 frame_id);
 142
 143   // Called when a client property changes.
 144   OnFrameClientPropertyChanged(uint32 frame_id,
 145                                string name,
 146                                array<uint8>? new_value);
 147
 148   // See description in PostMessageEventToFrame().
 149   OnPostMessageEvent(uint32 source_frame_id,
 150                      uint32 target_frame_id,
 151                      HTMLMessageEvent event);
 152
 153   // Called prior to starting a new navigation in |target_frame_id|. This is
 154   // only called on the FrameTreeClient that is rendering to |target_frame_id|
 155   // and only when another content handler is going to start handling the
 156   // rendering.
 157   OnWillNavigate(uint32 target_frame_id);
 158 };