// Copyright 2017 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 blink.mojom;

import "media/capture/mojom/video_capture_types.mojom";
import "media/mojo/mojom/audio_parameters.mojom";
import "media/mojo/mojom/display_media_information.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";

// Types of media streams. When updating this list, make sure to update the
// predicates declared in content/public/browser/media_stream_request.h,
// e.g. IsVideoScreenCaptureMediaType().
enum MediaStreamType {
  NO_SERVICE,

  // A device provided by the operating system (e.g., webcam input).
  DEVICE_AUDIO_CAPTURE,
  DEVICE_VIDEO_CAPTURE,

  // Below GUM_* types represent the streams generated by
  // getUserMedia() calls with constraints that are collected with legacy
  // APIs for desktop and tab capture.
  // Mirroring of a browser tab.
  GUM_TAB_AUDIO_CAPTURE,
  GUM_TAB_VIDEO_CAPTURE,

  // Desktop media sources.
  GUM_DESKTOP_VIDEO_CAPTURE,
  // Capture system audio (post-mix loopback stream).
  GUM_DESKTOP_AUDIO_CAPTURE,

  // Enables the capture of a user's display, generated by getDisplayMedia()
  // call.
  DISPLAY_VIDEO_CAPTURE,
  DISPLAY_AUDIO_CAPTURE,

  // Enables the capture of a user's display. Like DISPLAY_VIDEO_CAPTURE, this
  // is generated by the Screen Capture API (www.w3.org/TR/screen-capture/).
  // Unlike DISPLAY_VIDEO_CAPTURE, this one specifies that the current tab
  // is the one that should be captured.
  DISPLAY_VIDEO_CAPTURE_THIS_TAB,

  // TODO(crbug.com/971228): Remove NUM_MEDIA_TYPES, as per the conventions
  // in docs/security/mojo.md#do-not-define-placeholder-enumerator-values.
  NUM_MEDIA_TYPES
};

// Elements in this enum should not be deleted or rearranged; the only
// permitted operation is to add new elements before NUM_MEDIA_REQUEST_RESULTS.
enum MediaStreamRequestResult {
  OK,
  PERMISSION_DENIED,
  PERMISSION_DISMISSED,
  INVALID_STATE,
  NO_HARDWARE,
  INVALID_SECURITY_ORIGIN,
  TAB_CAPTURE_FAILURE,
  SCREEN_CAPTURE_FAILURE,
  CAPTURE_FAILURE,
  CONSTRAINT_NOT_SATISFIED,
  TRACK_START_FAILURE_AUDIO,
  TRACK_START_FAILURE_VIDEO,
  NOT_SUPPORTED,
  FAILED_DUE_TO_SHUTDOWN,
  KILL_SWITCH_ON,
  SYSTEM_PERMISSION_DENIED,
  NUM_MEDIA_REQUEST_RESULTS
};

// Strategies used to search an audio device stream.
enum StreamSelectionStrategy {
  SEARCH_BY_SESSION_ID,
  SEARCH_BY_DEVICE_ID,
  FORCE_NEW_STREAM,
};

// Type of state change for the corresponding requests.
enum MediaStreamStateChange {
  PLAY,
  PAUSE,
};

// See MediaStreamDispatcherHost below for information.
struct StreamSelectionInfo {
  StreamSelectionStrategy strategy;
  // When |strategy| is set to be SEARCH_BY_SESSION_ID, |session_id| must be
  // specified and valid. It can be null otherwise.
  mojo_base.mojom.UnguessableToken? session_id;
};

// See public/common/media_stream_request.h.
struct MediaStreamDevice {
  MediaStreamType type;
  string id;
  media.mojom.VideoFacingMode video_facing;
  string? group_id;
  string? matched_output_device_id;
  string name;
  media.mojom.AudioParameters input;
  mojo_base.mojom.UnguessableToken? session_id;
  media.mojom.DisplayMediaInformation? display_media_info;
};

// See common/media/media_stream_controls.h.
struct TrackControls {
  bool requested;
  MediaStreamType stream_type;
  string device_id;
};

// See common/media/media_stream_controls.h.
struct StreamControls {
  TrackControls audio;
  TrackControls video;
  bool hotword_enabled;
  bool disable_local_echo;
  bool request_pan_tilt_zoom_permission;
};

// Per-frame renderer-side interface that receives device stopped/change
// notifications or pause requests from the browser process.
interface MediaStreamDeviceObserver {
  OnDeviceStopped(string label, MediaStreamDevice device);
  OnDeviceChanged(string label,
                  MediaStreamDevice old_device,
                  MediaStreamDevice new_device);
  // Requests to pause or resume the corresponding media stream device.
  OnDeviceRequestStateChange(string label, MediaStreamDevice device, MediaStreamStateChange new_state);
};

// Per-frame browser-side interface that is used by the renderer process to
// make media stream requests.
interface MediaStreamDispatcherHost {
  // Requests a new media stream.
  // |request_id| is used by the renderer to identify the stream generation
  // request.
  // |controls| contains track-related settings such as device ID or MediaStream
  // type.
  // |user_gesture| indicates whether the call was made in the context of a user
  // gesture.
  // |audio_stream_selection_info| is used to request a specific stream using
  // the associated session ID and is only used for audio devices when
  // |audio_stream_selection_info.strategy| is SEARCH_BY_SESSION_ID; when it is
  // FORCE_NEW_STREAM, a new stream with a new session ID is always generated;
  // finally, when it is SEARCH_BY_DEVICE_ID, an existing stream is used if the
  // device associated to the request already has an opened stream available, or
  // a new one otherwise.
  GenerateStream(int32 request_id, StreamControls controls, bool user_gesture,
                 StreamSelectionInfo audio_stream_selection_info)
      => (MediaStreamRequestResult result, string label,
         array<MediaStreamDevice> audio_devices,
         array<MediaStreamDevice> video_devices,
         bool pan_tilt_zoom_allowed);

  // Cancels the request for a new media stream or opening a device.
  CancelRequest(int32 request_id);

  // Closes a stream device that has been opened by GenerateStream.
  StopStreamDevice(string device_id, mojo_base.mojom.UnguessableToken? session_id);

  // Opens a device identified by |device_id|.
  OpenDevice(int32 request_id, string device_id, MediaStreamType type)
      => (bool success, string label, MediaStreamDevice device);

  // Cancels an open request identified by |label|.
  CloseDevice(string label);

  // Tells the browser process if the video capture is secure (i.e., all
  // connected video sinks meet the requirement of output protection.).
  // Note: the browser process only trusts the |is_secure| value in this Mojo
  // message if it's comimg from a trusted, whitelisted extension. Extensions
  // run in separate render processes. So it shouldn't be possible, for example,
  // for a user's visit to a malicious web page to compromise a render process
  // running a trusted extension to make it report falsehood in this Mojo
  // message.
  SetCapturingLinkSecured(mojo_base.mojom.UnguessableToken? session_id, MediaStreamType type,
                          bool is_secure);

  // Tells the browser process that the stream has been started successfully.
  OnStreamStarted(string label);
};

// Browser-side interface that is used by the renderer process to notify the
// addition or deletion of tracks.
interface MediaStreamTrackMetricsHost {
  // Adds the track with the specified information to the list of tracks.
  AddTrack(uint64 id, bool is_audio, bool is_remote);

  // Removes the track with the specified ID from the list of tracks.
  RemoveTrack(uint64 id);
};