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