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 GalleryChangeType {
  10     // The contents of the gallery have changed.
  11     contents_changed,
  12     // The watch has been dropped because the device has been detached,
  13     // the gallery permission has been removed, or any other reason.
  14     watch_dropped
  15   };
  16
  17   [inline_doc] enum GetMediaFileSystemsInteractivity {
  18     // Do not act interactively.
  19     no,
  20     // Ask the user to manage permitted media galleries.
  21     yes,
  22     // Ask the user to manage permitted galleries only if the return set would
  23     // otherwise be empty.
  24     if_needed
  25   };
  26
  27   [inline_doc] enum GetMetadataType {
  28     // Retrieve the mime type, metadata tags, and attached images.
  29     all,
  30     // Retrieve only the mime type and the metadata tags.
  31     mimeTypeAndTags,
  32     // Retrieve only the mime type.
  33     mimeTypeOnly
  34   };
  35
  36   [inline_doc] enum ScanProgressType {
  37     // The scan started.
  38     start,
  39     // The scan was cancelled.
  40     cancel,
  41     // The scan finished but none of the result have been added,
  42     // addScanResults() has to be called to ask the user for permission.
  43     finish,
  44     // The scan encountered an error and could not proceed.
  45     error
  46   };
  47
  48   [inline_doc] dictionary GalleryChangeDetails {
  49     // Type of change event.
  50     GalleryChangeType type;
  51
  52     // Identifies the modified gallery.
  53     DOMString galleryId;
  54   };
  55
  56   [inline_doc] dictionary MediaFileSystemsDetails {
  57     // Whether to prompt the user for permission to additional media galleries
  58     // before returning the permitted set. Default is silent.  If the value
  59     // 'yes' is passed, or if the application has not been granted access to
  60     // any media galleries and the value 'if_needed' is passed, then the
  61     // media gallery configuration dialog will be displayed.
  62     GetMediaFileSystemsInteractivity? interactive;
  63   };
  64
  65   [inline_doc] dictionary MediaMetadataOptions {
  66     // Specifies which subset of the metadata to retrieve. Defaults to 'all'
  67     // if the option is omitted.
  68     GetMetadataType? metadataType;
  69   };
  70
  71   callback MediaFileSystemsCallback =
  72       void ([instanceOf=DOMFileSystem] object[] mediaFileSystems);
  73
  74   callback AddUserFolderCallback =
  75       void ([instanceOf=DOMFileSystem] object[] mediaFileSystems,
  76             DOMString selectedFileSystemName);
  77
  78   callback DropPermissionForMediaFileSystemCallback = void ();
  79
  80   [inline_doc] dictionary MediaFileSystemMetadata {
  81     // The name of the file system.
  82     DOMString name;
  83
  84     // A unique and persistent id for the media gallery.
  85     DOMString galleryId;
  86
  87     // If the media gallery is on a removable device, a unique id for the
  88     // device while the device is online.
  89     DOMString? deviceId;
  90
  91     // True if the media gallery is on a removable device.
  92     boolean isRemovable;
  93
  94     // True if the device the media gallery is on was detected as a media
  95     // device.  i.e. a PTP or MTP device, or a DCIM directory is present.
  96     boolean isMediaDevice;
  97
  98     // True if the device is currently available.
  99     boolean isAvailable;
 100   };
 101
 102   [inline_doc] dictionary ScanProgressDetails {
 103     // The type of progress event, i.e. start, finish, etc.
 104     ScanProgressType type;
 105
 106     // The number of Galleries found.
 107     long? galleryCount;
 108
 109     // Appoximate number of media files found; some file types can be either
 110     // audio or video and are included in both counts.
 111     long? audioCount;
 112     long? imageCount;
 113     long? videoCount;
 114   };
 115
 116   callback MediaFileSystemsMetadataCallback =
 117       void (MediaFileSystemMetadata[] metadata);
 118
 119   dictionary StreamInfo {
 120     // Describes format of container or codec of stream, i.e. "mp3", "h264".
 121     DOMString type;
 122
 123     // An unfiltered string->string dictionary of tags for the stream.
 124     object tags;
 125   };
 126
 127   dictionary MediaMetadata {
 128     // The browser sniffed mime type.
 129     DOMString mimeType;
 130
 131     // Defined for images and video. In pixels.
 132     long? height;
 133     long? width;
 134
 135     // Defined for images only.
 136     double? xResolution;
 137     double? yResolution;
 138
 139     // Defined for audio and video. In seconds.
 140     double? duration;
 141
 142     // Defined for images and video. In degrees.
 143     long? rotation;
 144
 145     // Defined for images only.
 146     DOMString? cameraMake;
 147     DOMString? cameraModel;
 148     double? exposureTimeSeconds;
 149     boolean? flashFired;
 150     double? fNumber;
 151     double? focalLengthMm;
 152     double? isoEquivalent;
 153
 154     // Defined for audio and video only.
 155     DOMString? album;
 156     DOMString? artist;
 157     DOMString? comment;
 158     DOMString? copyright;
 159     long? disc;
 160     DOMString? genre;
 161     DOMString? language;
 162     DOMString? title;
 163     long? track;
 164
 165     // All the metadata in the media file. For formats with multiple streams,
 166     // stream order will be preserved. Container metadata is the first element.
 167     StreamInfo[] rawTags;
 168
 169     // The images embedded in the media file's metadata. This is most often
 170     // used for album art or video thumbnails.
 171     [instanceOf=Blob] object[] attachedImages;
 172   };
 173
 174   callback MediaMetadataCallback = void (MediaMetadata metadata);
 175
 176   // A dictionary that describes the add gallery watch request results.
 177   dictionary AddGalleryWatchResult {
 178     DOMString galleryId;
 179     boolean success;
 180   };
 181
 182   callback AddGalleryWatchCallback = void (AddGalleryWatchResult result);
 183   callback GetAllGalleryWatchCallback = void (DOMString[] galleryIds);
 184
 185   interface Functions {
 186     // Get the media galleries configured in this user agent. If none are
 187     // configured or available, the callback will receive an empty array.
 188     static void getMediaFileSystems(optional MediaFileSystemsDetails details,
 189                                     MediaFileSystemsCallback callback);
 190
 191     // Present a directory picker to the user and add the selected directory
 192     // as a gallery. If the user cancels the picker, selectedFileSystemName
 193     // will be empty.
 194     // A user gesture is required for the dialog to display. Without a user
 195     // gesture, the callback will run as though the user canceled.
 196     static void addUserSelectedFolder(AddUserFolderCallback callback);
 197
 198     // Give up access to a given media gallery.
 199     static void dropPermissionForMediaFileSystem(
 200         DOMString galleryId,
 201         optional DropPermissionForMediaFileSystemCallback callback);
 202
 203     // Start a scan of the user's hard disks for directories containing media.
 204     // The scan may take a long time so progress and completion is communicated
 205     // by events. No permission is granted as a result of the scan, see
 206     // addScanResults.
 207     static void startMediaScan();
 208
 209     // Cancel any pending media scan.  Well behaved apps should provide a way
 210     // for the user to cancel scans they start.
 211     static void cancelMediaScan();
 212
 213     // Show the user the scan results and let them add any or all of them as
 214     // galleries. This should be used after the 'finish' onScanProgress()
 215     // event has happened. All galleries the app has access to are returned, not
 216     // just the newly added galleries.
 217     static void addScanResults(MediaFileSystemsCallback callback);
 218
 219     // Get metadata about a specific media file system.
 220     [nocompile] static MediaFileSystemMetadata getMediaFileSystemMetadata(
 221         [instanceOf=DOMFileSystem] object mediaFileSystem);
 222
 223     // Get metadata for all available media galleries.
 224     static void getAllMediaFileSystemMetadata(
 225         MediaFileSystemsMetadataCallback callback);
 226
 227     // Gets the media-specific metadata for a media file. This should work
 228     // for files in media galleries as well as other DOM filesystems.
 229     static void getMetadata([instanceOf=Blob] object mediaFile,
 230                             optional MediaMetadataOptions options,
 231                             MediaMetadataCallback callback);
 232
 233     // Adds a gallery watch for the gallery with the specified gallery ID.
 234     // The given callback is then fired with a success or failure result.
 235     static void addGalleryWatch(DOMString galleryId,
 236                                 AddGalleryWatchCallback callback);
 237
 238     // Removes a gallery watch for the gallery with the specified gallery ID.
 239     static void removeGalleryWatch(DOMString galleryId);
 240
 241     // Notifies which galleries are being watched via the given callback.
 242     static void getAllGalleryWatch(GetAllGalleryWatchCallback callback);
 243
 244     // Removes all gallery watches.
 245     static void removeAllGalleryWatch();
 246   };
 247
 248   interface Events {
 249     // Fired when a media gallery is changed or a gallery watch is dropped.
 250     static void onGalleryChanged(GalleryChangeDetails details);
 251
 252     // The pending media scan has changed state. See details for more
 253     // information.
 254     static void onScanProgress(ScanProgressDetails details);
 255   };
 256 };