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 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   interface Functions {
 177     // Get the media galleries configured in this user agent. If none are
 178     // configured or available, the callback will receive an empty array.
 179     static void getMediaFileSystems(optional MediaFileSystemsDetails details,
 180                                     MediaFileSystemsCallback callback);
 181
 182     // Present a directory picker to the user and add the selected directory
 183     // as a gallery. If the user cancels the picker, selectedFileSystemName
 184     // will be empty.
 185     // A user gesture is required for the dialog to display. Without a user
 186     // gesture, the callback will run as though the user canceled.
 187     static void addUserSelectedFolder(AddUserFolderCallback callback);
 188
 189     // Give up access to a given media gallery.
 190     static void dropPermissionForMediaFileSystem(
 191         DOMString galleryId,
 192         optional DropPermissionForMediaFileSystemCallback callback);
 193
 194     // Start a scan of the user's hard disks for directories containing media.
 195     // The scan may take a long time so progress and completion is communicated
 196     // by events. No permission is granted as a result of the scan, see
 197     // addScanResults.
 198     static void startMediaScan();
 199
 200     // Cancel any pending media scan.  Well behaved apps should provide a way
 201     // for the user to cancel scans they start.
 202     static void cancelMediaScan();
 203
 204     // Show the user the scan results and let them add any or all of them as
 205     // galleries. This should be used after the 'finish' onScanProgress()
 206     // event has happened. All galleries the app has access to are returned, not
 207     // just the newly added galleries.
 208     static void addScanResults(MediaFileSystemsCallback callback);
 209
 210     // Get metadata about a specific media file system.
 211     [nocompile] static MediaFileSystemMetadata getMediaFileSystemMetadata(
 212         [instanceOf=DOMFileSystem] object mediaFileSystem);
 213
 214     // Get metadata for all available media galleries.
 215     static void getAllMediaFileSystemMetadata(
 216         MediaFileSystemsMetadataCallback callback);
 217
 218     // Gets the media-specific metadata for a media file. This should work
 219     // for files in media galleries as well as other DOM filesystems.
 220     static void getMetadata([instanceOf=Blob] object mediaFile,
 221                             optional MediaMetadataOptions options,
 222                             MediaMetadataCallback callback);
 223   };
 224
 225   interface Events {
 226     // Fired when a media gallery is changed or a gallery watch is dropped.
 227     static void onGalleryChanged(GalleryChangeDetails details);
 228
 229     // The pending media scan has changed state. See details for more
 230     // information.
 231     static void onScanProgress(ScanProgressDetails details);
 232   };
 233 };