// Copyright (c) 2012 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.

// Use the <code>chrome.mediaGalleries</code> API to access media files (images,
// video, audio) from the user's local disks (with the user's consent).
namespace mediaGalleries {

  [inline_doc] enum GetMediaFileSystemsInteractivity {
    // Do not act interactively.
    no,
    // Ask the user to manage permitted media galleries.
    yes,
    // Ask the user to manage permitted galleries only if the return set would
    // otherwise be empty.
    if_needed
  };

  enum GetMetadataType {
    // Retrieve all available metadata.
    all,
    // Retrieve only the mime type.
    mimeTypeOnly
  };

  [inline_doc] dictionary MediaFileSystemsDetails {
    // Whether to prompt the user for permission to additional media galleries
    // before returning the permitted set. Default is silent.  If the value
    // 'yes' is passed, or if the application has not been granted access to
    // any media galleries and the value 'if_needed' is passed, then the
    // media gallery configuration dialog will be displayed.
    GetMediaFileSystemsInteractivity? interactive;
  };

  dictionary MediaMetadataOptions {
    // Specifies which subset of the metadata to retrieve. Defaults to 'all'
    // if the option is omitted.
    GetMetadataType? metadataType;
  };

  callback MediaFileSystemsCallback =
      void ([instanceOf=DOMFileSystem] optional object[] mediaFileSystems);

  [inline_doc] dictionary MediaFileSystemMetadata {
    // The name of the file system.
    DOMString name;

    // A unique and persistent id for the media gallery.
    DOMString galleryId;

    // If the media gallery is on a removable device, a unique id for the
    // device while the device is online.
    DOMString? deviceId;

    // True if the media gallery is on a removable device.
    boolean isRemovable;

    // True if the device the media gallery is on was detected as a media
    // device.  i.e. a PTP or MTP device, or a DCIM directory is present.
    boolean isMediaDevice;

    // True if the device is currently available.
    boolean isAvailable;
  };

  callback MediaFileSystemsMetadataCallback =
      void (MediaFileSystemMetadata[] metadata);

  dictionary MediaMetadata {
    // The browser sniffed mime type.
    DOMString mimeType;
  };

  callback MediaMetadataCallback = void (MediaMetadata metadata);

  interface Functions {
    // Get the media galleries configured in this user agent. If none are
    // configured or available, the callback will receive an empty array.
    static void getMediaFileSystems(optional MediaFileSystemsDetails details,
                                    MediaFileSystemsCallback callback);

    // Get metadata about a specific media file system.
    [nocompile] static MediaFileSystemMetadata getMediaFileSystemMetadata(
        [instanceOf=DOMFileSystem] object mediaFileSystem);

    // Get metadata for all available media galleries.
    static void getAllMediaFileSystemMetadata(
        MediaFileSystemsMetadataCallback callback);
                
    // Gets the media-specific metadata for a media file. This should work
    // for files in media galleries as well as other DOM filesystems.
    static void getMetadata([instanceOf=Blob] object mediaFile,
                            optional MediaMetadataOptions options,
                            MediaMetadataCallback callback);
  };

};