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

// Desktop Capture API that can be used to capture content of screen or
// individual windows or tabs.
namespace desktopCapture {
  // Enum used to define set of desktop media sources used in
  // chooseDesktopMedia().
  enum DesktopCaptureSourceType {
    screen,
    window,
    tab
  };

  // |streamId|: An opaque string that can be passed to
  // <code>getUserMedia()</code> API to generate media stream that corresponds
  // to the source selected by the user. If user didn't select any source
  // (i.e. canceled the prompt) then the callback is called with an empty
  // <code>streamId</code>.
  callback ChooseDesktopMediaCallback = void (DOMString streamId);

  interface Functions {
    // Shows desktop media picker UI with the specified set of sources. Returns
    // an id that can be passed to cancelChooseDesktopMedia() in case the prompt
    // need to be canceled.
    //
    // |sources|: Set of sources that should be shown to the user.
    //
    // |origin|: Optional origin of the page for which the stream is created. If
    // not specified then the resulting stream can be used only the calling
    // extension, otherwise the stream can be used only by a page with the
    // specified origin.
    static long chooseDesktopMedia(DesktopCaptureSourceType[] sources,
                                   optional DOMString origin,
                                   ChooseDesktopMediaCallback callback);

    // Hides desktop media picker dialog shown by chooseDesktopMedia().
    //
    // |desktopMediaRequestId|: Id returned by chooseDesktopMedia()
    static void cancelChooseDesktopMedia(long desktopMediaRequestId);
  };
};