src/chrome/common/extensions/api/media_galleries.idl

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.mediaGalleries</code> API to access media files (audio,
   6 // images, video) from the user's local disks (with the user's consent).
   7 namespace mediaGalleries {
   8
   9   [inline_doc] enum GetMediaFileSystemsInteractivity {
  10     // Do not act interactively.
  11     no,
  12     // Ask the user to manage permitted media galleries.
  13     yes,
  14     // Ask the user to manage permitted galleries only if the return set would
  15     // otherwise be empty.
  16     if_needed
  17   };
  18
  19   [inline_doc] enum GetMetadataType {
  20     // Retrieve all available metadata.
  21     all,
  22     // Retrieve only the mime type.
  23     mimeTypeOnly
  24   };
  25
  26   [inline_doc] enum ScanProgressType {
  27     // The scan started.
  28     start,
  29     // The scan was cancelled.
  30     cancel,
  31     // The scan finished but none of the result have been added,
  32     // addScanResults() has to be called to ask the user for permission.
  33     finish,
  34     // The scan encountered an error and could not proceed.
  35     error
  36   };
  37
  38   [inline_doc] dictionary MediaFileSystemsDetails {
  39     // Whether to prompt the user for permission to additional media galleries
  40     // before returning the permitted set. Default is silent.  If the value
  41     // 'yes' is passed, or if the application has not been granted access to
  42     // any media galleries and the value 'if_needed' is passed, then the
  43     // media gallery configuration dialog will be displayed.
  44     GetMediaFileSystemsInteractivity? interactive;
  45   };
  46
  47   [inline_doc] dictionary MediaMetadataOptions {
  48     // Specifies which subset of the metadata to retrieve. Defaults to 'all'
  49     // if the option is omitted.
  50     GetMetadataType? metadataType;
  51   };
  52
  53   callback MediaFileSystemsCallback =
  54       void ([instanceOf=DOMFileSystem] optional object[] mediaFileSystems);
  55
  56   callback AddUserFolderCallback =
  57       void ([instanceOf=DOMFileSystem] object[] mediaFileSystems,
  58             DOMString selectedFileSystemName);
  59
  60   [inline_doc] dictionary MediaFileSystemMetadata {
  61     // The name of the file system.
  62     DOMString name;
  63
  64     // A unique and persistent id for the media gallery.
  65     DOMString galleryId;
  66
  67     // If the media gallery is on a removable device, a unique id for the
  68     // device while the device is online.
  69     DOMString? deviceId;
  70
  71     // True if the media gallery is on a removable device.
  72     boolean isRemovable;
  73
  74     // True if the device the media gallery is on was detected as a media
  75     // device.  i.e. a PTP or MTP device, or a DCIM directory is present.
  76     boolean isMediaDevice;
  77
  78     // True if the device is currently available.
  79     boolean isAvailable;
  80   };
  81
  82   [inline_doc] dictionary ScanProgressDetails {
  83     // The type of progress event, i.e. start, finish, etc.
  84     ScanProgressType type;
  85
  86     // The number of Galleries found.
  87     long? galleryCount;
  88
  89     // Appoximate number of media files found; some file types can be either
  90     // audio or video and are included in both counts.
  91     long? audioCount;
  92     long? imageCount;
  93     long? videoCount;
  94   };
  95
  96   callback MediaFileSystemsMetadataCallback =
  97       void (MediaFileSystemMetadata[] metadata);
  98
  99   dictionary MediaMetadata {
 100     // The browser sniffed mime type.
 101     DOMString mimeType;
 102
 103     // Defined for images and video. In pixels.
 104     long? height;
 105     long? width;
 106
 107     // Defined for audio and video. In seconds.
 108     double? duration;
 109
 110     // Defined for images and video. In degrees.
 111     long? rotation;
 112
 113     // Generic metadata tags.
 114     DOMString? album;
 115     DOMString? artist;
 116     DOMString? comment;
 117     DOMString? copyright;
 118     long? disc;
 119     DOMString? genre;
 120     DOMString? language;
 121     DOMString? title;
 122     long? track;
 123   };
 124
 125   callback MediaMetadataCallback = void (MediaMetadata metadata);
 126
 127   interface Functions {
 128     // Get the media galleries configured in this user agent. If none are
 129     // configured or available, the callback will receive an empty array.
 130     static void getMediaFileSystems(optional MediaFileSystemsDetails details,
 131                                     MediaFileSystemsCallback callback);
 132
 133     // Present a directory picker to the user and add the selected directory
 134     // as a gallery. If the user cancels the picker, selectedFileSystemName
 135     // will be empty.
 136     // A user gesture is required for the dialog to display. Without a user
 137     // gesture, the callback will run as though the user canceled.
 138     static void addUserSelectedFolder(AddUserFolderCallback callback);
 139
 140     // Start a scan of the user's hard disks for directories containing media.
 141     // The scan may take a long time so progress and completion is communicated
 142     // by events. No permission is granted as a result of the scan, see
 143     // addScanResults.
 144     static void startMediaScan();
 145
 146     // Cancel any pending media scan.  Well behaved apps should provide a way
 147     // for the user to cancel scans they start.
 148     static void cancelMediaScan();
 149
 150     // Show the user the scan results and let them add any or all of them as
 151     // galleries. This should be used after the 'finish' onScanProgress()
 152     // event has happened. A galleries the app has access to are returned, not
 153     // just the newly added galleries.
 154     static void addScanResults(MediaFileSystemsCallback callback);
 155
 156     // Get metadata about a specific media file system.
 157     [nocompile] static MediaFileSystemMetadata getMediaFileSystemMetadata(
 158         [instanceOf=DOMFileSystem] object mediaFileSystem);
 159
 160     // Get metadata for all available media galleries.
 161     static void getAllMediaFileSystemMetadata(
 162         MediaFileSystemsMetadataCallback callback);
 163
 164     // Gets the media-specific metadata for a media file. This should work
 165     // for files in media galleries as well as other DOM filesystems.
 166     static void getMetadata([instanceOf=Blob] object mediaFile,
 167                             optional MediaMetadataOptions options,
 168                             MediaMetadataCallback callback);
 169   };
 170
 171   interface Events {
 172     // The pending media scan has changed state. See details for more
 173     // information.
 174     static void onScanProgress(ScanProgressDetails details);
 175   };
 176 };