// Copyright 2020 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.

module content.mojom;

import "content/public/common/webplugininfo.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/process_id.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

// Generic Pepper messages. Implemented by the browser.
interface PepperHost {
  // Notification that a Pepper plugin instance is created in the DOM.
  InstanceCreated(int32 instance_id,
                  pending_associated_remote<PepperPluginInstance> instance,
                  pending_associated_receiver<PepperPluginInstanceHost> host);

  // Bind a PepperHungDetectorHost. The interface will be used to inform the
  // browser that a renderer's plugin module has been blocked for too long.
  BindHungDetectorHost(pending_receiver<PepperHungDetectorHost> host,
             int32 plugin_child_id,
             mojo_base.mojom.FilePath plugin_path);

  // Return information about a plugin for the given URL and MIME
  // type. If there is no matching plugin, |found| is false.
  // |actual_mime_type| is the actual mime type supported by the
  // found plugin.
  [Sync]
  GetPluginInfo(url.mojom.Url url,
                string mime_type) =>
               (bool found,
                content.mojom.WebPluginInfo plugin_info,
                string actual_mime_type);

  // Notification an in-process instance has been created.
  DidCreateInProcessInstance(int32 instance_id,
                             int32 frame_routing_id,
                             url.mojom.Url document_url,
                             url.mojom.Url plugin_url);

  // Notification that an in-process instance has been destroyed.
  DidDeleteInProcessInstance(int32 instance_id);

  // Notification that a plugin has created a new plugin instance. The
  // parameters indicate:
  //  - The plugin process ID that we're creating the instance for.
  //  - The instance ID of the instance being created.
  //  - A PepperRendererInstanceData struct which contains properties from the
  //    renderer which are associated with the plugin instance. This includes
  //    the routing ID of the associated RenderFrame and the URL of plugin.
  //  - Whether the plugin we're creating an instance for is external or
  //    internal.
  //
  // This message must be sync even though it returns no parameters to avoid
  // a race condition with the plugin process. The plugin process sends messages
  // to the browser that assume the browser knows about the instance. We need to
  // make sure that the browser actually knows about the instance before we tell
  // the plugin to run.
  [Sync]
  DidCreateOutOfProcessPepperInstance(int32 plugin_child_id,
                                      int32 pp_instance,
                                      bool is_external,
                                      int32 frame_routing_id,
                                      url.mojom.Url document_url,
                                      url.mojom.Url plugin_url,
                                      bool is_privileged_context) => ();

  // Notification that a plugin has destroyed an instance.
  DidDeleteOutOfProcessPepperInstance(int32 plugin_child_id,
                                      int32 pp_instance,
                                      bool is_external);

  // A renderer sends this to the browser process when it wants to create a
  // ppapi plugin.  The browser will create the plugin process if necessary,
  // and will return a handle to the channel on success.
  //
  // The plugin_child_id is the ChildProcessHost ID assigned in the browser
  // process. This ID is valid only in the context of the browser process and is
  // used to identify the proper process when the renderer notifies it that the
  // plugin is hung.
  //
  // |embedder_origin| provides the origin of the frame that embeds the plugin
  // (i.e. the origin of the document that contains the <embed> html tag).
  // |embedder_origin| needs to be included in the message payload, because the
  // message is received and handled on the IO thread in the browser process
  // (where it is not possible to consult
  // RenderFrameHostImpl::GetLastCommittedOrigin).
  //
  // On error null handles are returned.
  [Sync]
  OpenChannelToPepperPlugin(url.mojom.Origin embedder_origin,
                            mojo_base.mojom.FilePath path,
                            url.mojom.Origin? origin_lock) =>
                           (handle<message_pipe>? handle_to_channel,
                            mojo_base.mojom.ProcessId plugin_pid,
                            int32 plugin_child_id);
};

// This interface is used on the renderer IO thread and is received on the
// browser UI thread for determining an out of process pepper plugin container
// has not responded to the renderer for too long.
interface PepperHungDetectorHost {
  // Sent to the browser when the renderer detects it is blocked on a pepper
  // plugin message for too long. This is also sent when it becomes unhung
  // (according to the value of is_hung). The browser can give the user the
  // option of killing the plugin.
  PluginHung(bool is_hung);
};

// Plugin instance specific host messages that are sent from the renderer
// main thread and dispatched on the UI thread of the browser. Implemented by
// the browser.
interface PepperPluginInstanceHost {
  // Notification a plugin instance has started playback.
  StartsPlayback();

  // Notification a plugin instance has stopped playback.
  StopsPlayback();

  // Notification that a plugin instance has crashed.
  // Note: |plugin_pid| should not be trusted. The corresponding process has
  // probably died. Moreover, the ID may have been reused by a new process. Any
  // usage other than displaying it in a prompt to the user is very likely to be
  // wrong.
  InstanceCrashed(mojo_base.mojom.FilePath plugin_path,
                  mojo_base.mojom.ProcessId plugin_pid);
};

// Plugin instance specific messages. Implemented by the renderer.
interface PepperPluginInstance {
  // Set the volume of a plugin. |volume| should be in the [0, 1] range.
  SetVolume(double volume);
};