Home | History | Annotate | Download | only in api 
      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.recovery</code> API to write images to
      6 // removable media.
      7 [nodoc] namespace recoveryPrivate {
      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>write</dt>
     20   //    <dd>The image is being written to disk.</dd>
     21   //    <dt>verifyWrite</dt>
     22   //    <dt>The system is verifying that the written image matches the
     23   //    downloaded image.</dd>
     24   // <dl>
     25   enum Stage {
     26     confirmation,
     27     download,
     28     verifyDownload,
     29     write,
     30     verifyWrite
     31   };
     32 
     33   // Options for writing an image.
     34   dictionary UrlWriteOptions {
     35     // If present, verify that the downloaded image matches this hash.
     36     DOMString? imageHash;
     37     // If true, save the downloaded image as a file using the user's downloads
     38     // preferences.
     39     boolean? saveAsDownload;
     40   };
     41 
     42   dictionary ProgressInfo {
     43     // The $ref:Stage that the write process is currently in.
     44     Stage stage;
     45     // Current progress within the stage.
     46     long percentComplete;
     47   };
     48 
     49   callback WriteImageCallback = void ();
     50   callback WriteCancelCallback = void ();
     51   callback DestroyPartitionsCallback = void ();
     52 
     53   interface Functions {
     54     // Write an image to the disk downloaded from the provided URL.  The
     55     // callback will be called when the entire operation completes, either
     56     // successfully or on error.
     57     //
     58     // |storageUnitId|: The identifier for the storage unit, as provided by
     59     // experimental.system_info.storage.
     60     // |options|: If present the imageUrl of the options will be used to
     61     // download the image.  Otherwise the user will be prompted for a local
     62     // image to burn.
     63     // |callback|: The callback which signifies that the write operation has
     64     // been started by the system and provides a unique ID for this operation.
     65     static void writeFromUrl(DOMString storageUnitId,
     66                              DOMString imageUrl,
     67                              optional UrlWriteOptions options,
     68                              WriteImageCallback callback);
     69 
     70     // Write an image to the disk, prompting the user to supply the image from
     71     // a local file.  The callback will be called when the entire operation
     72     // completes, either successfully or on error.
     73     //
     74     // |storageUnitId|: The identifier for the storage unit, as provided by
     75     // experimental.system_info.storage.
     76     // |options|: If present the imageUrl of the options will be used to
     77     // download the image.  Otherwise the user will be prompted for a local
     78     // image to burn.
     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 writeFromFile(DOMString storageUnitId,
     82                               WriteImageCallback callback);
     83 
     84     // Cancel a current write operation.
     85     //
     86     // |callback|: The callback which is triggered with the write is
     87     // successfully cancelled, passing the $ref:ProgressInfo of the operation at
     88     // the time it was cancelled.
     89     static boolean cancelWrite(WriteCancelCallback callback);
     90 
     91     // Destroys the partition table of a disk, effectively erasing it.  This is
     92     // a fairly quick operation and so it does not have complex stages or
     93     // progress information.  However, it can fail and call the callback with
     94     // an error.
     95     //
     96     // |storageUnitId|: The identifier of the storage unit to wipe, as provided
     97     // by experimental.system_info.storage.
     98     // |callback|: A callback which is called when the operation is complete.
     99     static void destroyPartitions(DOMString storageUnitId,
    100                                   DestroyPartitionsCallback callback);
    101   };
    102 
    103   interface Events {
    104     // Fires periodically throughout the writing operation and at least once per
    105     // stage.
    106     static void onWriteProgress(ProgressInfo info);
    107     // Fires when the write operation has completely finished, such as all
    108     // devices being finalized and resources released.
    109     static void onWriteComplete();
    110     // Fires when an error occured during writing, passing the $ref:ProgressInfo
    111     // of the operation at the time the error occured.
    112     static void onWriteError(ProgressInfo info);
    113     // Fires when an error occured while destroying partitions.
    114     static void onDestroyPartitionsError();
    115   };
    116 
    117 };
    118 
    119