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] object[] mediaFileSystems);
  55
  56   callback AddUserFolderCallback =
  57       void ([instanceOf=DOMFileSystem] object[] mediaFileSystems,
  58             DOMString selectedFileSystemName);
  59
  60   callback DropPermissionForMediaFileSystemCallback = void ();
  61
  62   [inline_doc] dictionary MediaFileSystemMetadata {
  63     // The name of the file system.
  64     DOMString name;
  65
  66     // A unique and persistent id for the media gallery.
  67     DOMString galleryId;
  68
  69     // If the media gallery is on a removable device, a unique id for the
  70     // device while the device is online.
  71     DOMString? deviceId;
  72
  73     // True if the media gallery is on a removable device.
  74     boolean isRemovable;
  75
  76     // True if the device the media gallery is on was detected as a media
  77     // device.  i.e. a PTP or MTP device, or a DCIM directory is present.
  78     boolean isMediaDevice;
  79
  80     // True if the device is currently available.
  81     boolean isAvailable;
  82   };
  83
  84   [inline_doc] dictionary ScanProgressDetails {
  85     // The type of progress event, i.e. start, finish, etc.
  86     ScanProgressType type;
  87
  88     // The number of Galleries found.
  89     long? galleryCount;
  90
  91     // Appoximate number of media files found; some file types can be either
  92     // audio or video and are included in both counts.
  93     long? audioCount;
  94     long? imageCount;
  95     long? videoCount;
  96   };
  97
  98   callback MediaFileSystemsMetadataCallback =
  99       void (MediaFileSystemMetadata[] metadata);
 100
 101   dictionary StreamInfo {
 102     // Describes format of container or codec of stream, i.e. "mp3", "h264".
 103     DOMString type;
 104
 105     // An unfiltered string->string dictionary of tags for the stream.
 106     object tags;
 107   };
 108
 109   dictionary MediaMetadata {
 110     // The browser sniffed mime type.
 111     DOMString mimeType;
 112
 113     // Defined for images and video. In pixels.
 114     long? height;
 115     long? width;
 116
 117     // Defined for images only.
 118     double? xResolution;
 119     double? yResolution;
 120
 121     // Defined for audio and video. In seconds.
 122     double? duration;
 123
 124     // Defined for images and video. In degrees.
 125     long? rotation;
 126
 127     // Defined for images only.
 128     DOMString? cameraMake;
 129     DOMString? cameraModel;
 130     double? exposureTimeSeconds;
 131     boolean? flashFired;
 132     double? fNumber;
 133     double? focalLengthMm;
 134     double? isoEquivalent;
 135
 136     // Defined for audio and video only.
 137     DOMString? album;
 138     DOMString? artist;
 139     DOMString? comment;
 140     DOMString? copyright;
 141     long? disc;
 142     DOMString? genre;
 143     DOMString? language;
 144     DOMString? title;
 145     long? track;
 146
 147     // All the metadata in the media file. For formats with multiple streams,
 148     // stream order will be preserved. Container metadata is the first element.
 149     StreamInfo[] rawTags;
 150   };
 151
 152   callback MediaMetadataCallback = void (MediaMetadata metadata);
 153
 154   interface Functions {
 155     // Get the media galleries configured in this user agent. If none are
 156     // configured or available, the callback will receive an empty array.
 157     static void getMediaFileSystems(optional MediaFileSystemsDetails details,
 158                                     MediaFileSystemsCallback callback);
 159
 160     // Present a directory picker to the user and add the selected directory
 161     // as a gallery. If the user cancels the picker, selectedFileSystemName
 162     // will be empty.
 163     // A user gesture is required for the dialog to display. Without a user
 164     // gesture, the callback will run as though the user canceled.
 165     static void addUserSelectedFolder(AddUserFolderCallback callback);
 166
 167     // Give up access to a given media gallery.
 168     static void dropPermissionForMediaFileSystem(
 169         DOMString galleryId,
 170         optional DropPermissionForMediaFileSystemCallback callback);
 171
 172     // Start a scan of the user's hard disks for directories containing media.
 173     // The scan may take a long time so progress and completion is communicated
 174     // by events. No permission is granted as a result of the scan, see
 175     // addScanResults.
 176     static void startMediaScan();
 177
 178     // Cancel any pending media scan.  Well behaved apps should provide a way
 179     // for the user to cancel scans they start.
 180     static void cancelMediaScan();
 181
 182     // Show the user the scan results and let them add any or all of them as
 183     // galleries. This should be used after the 'finish' onScanProgress()
 184     // event has happened. All galleries the app has access to are returned, not
 185     // just the newly added galleries.
 186     static void addScanResults(MediaFileSystemsCallback callback);
 187
 188     // Get metadata about a specific media file system.
 189     [nocompile] static MediaFileSystemMetadata getMediaFileSystemMetadata(
 190         [instanceOf=DOMFileSystem] object mediaFileSystem);
 191
 192     // Get metadata for all available media galleries.
 193     static void getAllMediaFileSystemMetadata(
 194         MediaFileSystemsMetadataCallback callback);
 195
 196     // Gets the media-specific metadata for a media file. This should work
 197     // for files in media galleries as well as other DOM filesystems.
 198     static void getMetadata([instanceOf=Blob] object mediaFile,
 199                             optional MediaMetadataOptions options,
 200                             MediaMetadataCallback callback);
 201   };
 202
 203   interface Events {
 204     // The pending media scan has changed state. See details for more
 205     // information.
 206     static void onScanProgress(ScanProgressDetails details);
 207   };
 208 };