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

   1 // Copyright 2013 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.image_writer</code> API to write images to
   6 // removable media.
   7 //
   8 // See the design doc for a detailed description of this API.
   9 // https://goto.google.com/image-writer-private-designdoc
  10 [nodoc] namespace imageWriterPrivate {
  11   // The different stages of a write call.
  12   //
  13   // <dl>
  14   //    <dt>confirmation</dt>
  15   //    <dd>The process starts by prompting the user for confirmation.</dd>
  16   //    <dt>download</dt>
  17   //    <dd>The image file is being download if a remote image was
  18   //    requested.</dd>
  19   //    <dt>verifyDownload</dt>
  20   //    <dd>The download is being verified to match the image hash, if
  21   //    provided</dd>
  22   //    <dt>unzip</dt>
  23   //    <dd>The image is being extracted from the downloaded zip file</dd>
  24   //    <dt>write</dt>
  25   //    <dd>The image is being written to disk.</dd>
  26   //    <dt>verifyWrite</dt>
  27   //    <dt>The system is verifying that the written image matches the
  28   //    downloaded image.</dd>
  29   // <dl>
  30   enum Stage {
  31     confirmation,
  32     download,
  33     verifyDownload,
  34     unzip,
  35     write,
  36     verifyWrite,
  37     unknown
  38   };
  39
  40   // Options for writing an image.
  41   dictionary UrlWriteOptions {
  42     // If present, verify that the downloaded image matches this hash.
  43     DOMString? imageHash;
  44     // If true, save the downloaded image as a file using the user's downloads
  45     // preferences.
  46     boolean? saveAsDownload;
  47   };
  48
  49   dictionary ProgressInfo {
  50     // The $(ref:Stage) that the write process is currently in.
  51     Stage stage;
  52     // Current progress within the stage.
  53     long percentComplete;
  54   };
  55
  56   dictionary RemovableStorageDevice {
  57     DOMString storageUnitId;
  58     double capacity;
  59     DOMString vendor;
  60     DOMString model;
  61   };
  62
  63   callback WriteImageCallback = void ();
  64   callback WriteCancelCallback = void ();
  65   callback ListRemovableStorageDevicesCallback = void (RemovableStorageDevice[] devices);
  66   callback DestroyPartitionsCallback = void ();
  67
  68   interface Functions {
  69     // Write an image to the disk downloaded from the provided URL.  The
  70     // callback will be called when the entire operation completes, either
  71     // successfully or on error.
  72     //
  73     // |storageUnitId|: The identifier for the storage unit
  74     // |imageUrl|: The url of the image to download which will be written
  75     // to the storage unit identified by |storageUnitId|
  76     // |options|: Optional parameters if comparing the download with a given
  77     // hash or saving the download to the users Downloads folder instead of a
  78     // temporary directory is desired
  79     // |callback|: The callback which signifies that the write operation has
  80     // been started by the system and provides a unique ID for this operation.
  81     static void writeFromUrl(DOMString storageUnitId,
  82                              DOMString imageUrl,
  83                              optional UrlWriteOptions options,
  84                              WriteImageCallback callback);
  85
  86     // Write an image to the disk, prompting the user to supply the image from
  87     // a local file.  The callback will be called when the entire operation
  88     // completes, either successfully or on error.
  89     //
  90     // |storageUnitId|: The identifier for the storage unit
  91     // |fileEntry|: The FileEntry object of the image to be burned.
  92     // |callback|: The callback which signifies that the write operation has
  93     // been started by the system and provides a unique ID for this operation.
  94     static void writeFromFile(DOMString storageUnitId,
  95                               [instanceOf=FileEntry] object fileEntry,
  96                               WriteImageCallback callback);
  97
  98     // Cancel a current write operation.
  99     //
 100     // |callback|: The callback which is triggered with the write is
 101     // successfully cancelled, passing the $(ref:ProgressInfo) of the operation at
 102     // the time it was cancelled.
 103     static boolean cancelWrite(WriteCancelCallback callback);
 104
 105     // Destroys the partition table of a disk, effectively erasing it.  This is
 106     // a fairly quick operation and so it does not have complex stages or
 107     // progress information, just a write phase.
 108     //
 109     // |storageUnitId|: The identifier of the storage unit to wipe
 110     // |callback|: A callback that triggers when the operation has been
 111     // successfully started.
 112     static void destroyPartitions(DOMString storageUnitId,
 113                                   DestroyPartitionsCallback callback);
 114
 115     // List all the removable block devices currently attached to the system.
 116     // |callback|: A callback called with a list of removable storage devices
 117     static void listRemovableStorageDevices(
 118         ListRemovableStorageDevicesCallback callback);
 119   };
 120
 121   interface Events {
 122     // Fires periodically throughout the writing operation and at least once per
 123     // stage.
 124     static void onWriteProgress(ProgressInfo info);
 125
 126     // Fires when the write operation has completely finished, such as all
 127     // devices being finalized and resources released.
 128     static void onWriteComplete();
 129
 130     // Fires when an error occured during writing, passing the $(ref:ProgressInfo)
 131     // of the operation at the time the error occured.
 132     static void onWriteError(ProgressInfo info, DOMString error);
 133
 134     // Fires when a removable storage device is inserted.
 135     static void onDeviceInserted(RemovableStorageDevice device);
 136
 137     // Fires when a removable storage device is removed.
 138     static void onDeviceRemoved(RemovableStorageDevice device);
 139   };
 140
 141 };
 142