// Copyright 2015 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 media.mojom;

import "media/mojo/interfaces/audio_decoder.mojom";
import "media/mojo/interfaces/cdm_proxy.mojom";
import "media/mojo/interfaces/decryptor.mojom";
import "media/mojo/interfaces/content_decryption_module.mojom";
import "media/mojo/interfaces/renderer.mojom";
import "media/mojo/interfaces/video_decoder.mojom";

// Defines the types of renderers that can be hosted by a mojo Renderer.
enum HostedRendererType {
  // media::DefaultRenderer: Used to offload normal rendering scenarios to a
  // different process, for stability or performance reasons.
  kDefault,

  // content::MediaPlayerRenderer: Used to handle HLS videos on Android. Also
  // used on older Android devices, that don't have platform decode support, and
  // are better off using the native Android MediaPlayer.
  [EnableIf=is_android]
  kMediaPlayer,

  // content::FlingingRenderer: Used to control a CastSession, in the context
  // of RemotePlayback. The CastSession must have already been started via the
  // PresentationService. This renderer does not actually render anything on the
  // local device, but instead serves as a link to/from media content playing on
  // a cast device.
  [EnableIf=is_android]
  kFlinging,
};

// A factory for creating media mojo interfaces. Renderers can only access
// ContentDecryptionModules created with the same factory.
interface InterfaceFactory {
  CreateAudioDecoder(AudioDecoder& audio_decoder);
  CreateVideoDecoder(VideoDecoder& video_decoder);

  // Creates a Renderer, using |type| to choose which concrete media::Renderer
  // implementation to host. Different values of |type| might affect how the
  // request is ultimately routed (i.e. |type| will determine in which process
  // the mojom::Renderer is created).
  // |type_specific_id| represents a different kind of ID, based off of |type|.
  // The usage of |type_specific_id| per |type| is defined as follows:
  // - kDefault: represents an audio device ID, which is defined in
  //   media/audio/audio_device_description.h.
  //   If |type_specific_id| is empty, kDefaultDeviceId will be used.
  // - kMediaPlayer: unused.
  // - kFlinging: represents a PresentationID for a session that has already
  //   been started. If the ID cannot be found (e.g. the session has already
  //   ended), CreateRenderer will be a no-op.
  CreateRenderer(HostedRendererType type, string type_specific_id,
                 Renderer& renderer);

  // Creates a CDM based on the |key_system| provided. A |key_system| is a
  // generic term for a decryption mechanism and/or content protection provider.
  // It should be a reverse domain name, e.g. "com.example.somesystem". However,
  // this call may be initiated by an untrusted process (e.g. renderer), so the
  // implementation must fully validate |key_system| before creating the CDM.
  CreateCdm(string key_system, ContentDecryptionModule& cdm);

  // Creates a Decryptor associated with the |cdm_id|.
  CreateDecryptor(int32 cdm_id, Decryptor& decryptor);

  // Creates a CdmProxy that proxies part of CDM functionalities to a different
  // entity, e.g. hardware CDM modules. The created |cdm_proxy| must match the
  // type of the CDM, identified by |cdm_guid|.
  // TODO(crbug.com/676224): Conditionally enable this when EnabledIf attribute
  // is supported in mojom files.
  // TODO(xhwang): Add a helper type for GUID to avoid passing string here.
  CreateCdmProxy(string cdm_guid, CdmProxy& cdm_proxy);
};