// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.image_writer</code> API to write images to
// removable media.
[nodoc] namespace imageWriterPrivate {
  // The different stages of a write call.
  //
  // <dl>
  //    <dt>confirmation</dt>
  //    <dd>The process starts by prompting the user for confirmation.</dd>
  //    <dt>download</dt>
  //    <dd>The image file is being download if a remote image was
  //    requested.</dd>
  //    <dt>verifyDownload</dt>
  //    <dd>The download is being verified to match the image hash, if
  //    provided</dd>
  //    <dt>unzip</dt>
  //    <dd>The image is being extracted from the downloaded zip file</dd>
  //    <dt>write</dt>
  //    <dd>The image is being written to disk.</dd>
  //    <dt>verifyWrite</dt>
  //    <dt>The system is verifying that the written image matches the
  //    downloaded image.</dd>
  // <dl>
  enum Stage {
    confirmation,
    download,
    verifyDownload,
    unzip,
    write,
    verifyWrite,
    unknown
  };

  // Options for writing an image.
  dictionary UrlWriteOptions {
    // If present, verify that the downloaded image matches this hash.
    DOMString? imageHash;
    // If true, save the downloaded image as a file using the user's downloads
    // preferences.
    boolean? saveAsDownload;
  };

  dictionary ProgressInfo {
    // The $(ref:Stage) that the write process is currently in.
    Stage stage;
    // Current progress within the stage.
    long percentComplete;
  };

  dictionary RemovableStorageDevice {
    DOMString storageUnitId;
    double capacity;
    DOMString vendor;
    DOMString model;
  };

  callback WriteImageCallback = void ();
  callback WriteCancelCallback = void ();
  callback ListRemovableStorageDevicesCallback = void (RemovableStorageDevice[] devices);
  callback DestroyPartitionsCallback = void ();

  interface Functions {
    // Write an image to the disk downloaded from the provided URL.  The
    // callback will be called when the entire operation completes, either
    // successfully or on error.
    //
    // |storageUnitId|: The identifier for the storage unit
    // |imageUrl|: The url of the image to download which will be written
    // to the storage unit identified by |storageUnitId|
    // |options|: Optional parameters if comparing the download with a given
    // hash or saving the download to the users Downloads folder instead of a
    // temporary directory is desired
    // |callback|: The callback which signifies that the write operation has
    // been started by the system and provides a unique ID for this operation.
    static void writeFromUrl(DOMString storageUnitId,
                             DOMString imageUrl,
                             optional UrlWriteOptions options,
                             WriteImageCallback callback);

    // Write an image to the disk, prompting the user to supply the image from
    // a local file.  The callback will be called when the entire operation
    // completes, either successfully or on error.
    //
    // |storageUnitId|: The identifier for the storage unit
    // |fileEntry|: The FileEntry object of the image to be burned.
    // |callback|: The callback which signifies that the write operation has
    // been started by the system and provides a unique ID for this operation.
    static void writeFromFile(DOMString storageUnitId,
                              [instanceOf=FileEntry] object fileEntry,
                              WriteImageCallback callback);

    // Cancel a current write operation.
    //
    // |callback|: The callback which is triggered with the write is
    // successfully cancelled, passing the $(ref:ProgressInfo) of the operation at
    // the time it was cancelled.
    static boolean cancelWrite(WriteCancelCallback callback);

    // Destroys the partition table of a disk, effectively erasing it.  This is
    // a fairly quick operation and so it does not have complex stages or
    // progress information, just a write phase.
    //
    // |storageUnitId|: The identifier of the storage unit to wipe
    // |callback|: A callback that triggers when the operation has been
    // successfully started.
    static void destroyPartitions(DOMString storageUnitId,
                                  DestroyPartitionsCallback callback);

    // List all the removable block devices currently attached to the system.
    // |callback|: A callback called with a list of removable storage devices
    static void listRemovableStorageDevices(
        ListRemovableStorageDevicesCallback callback);
  };

  interface Events {
    // Fires periodically throughout the writing operation and at least once per
    // stage.
    static void onWriteProgress(ProgressInfo info);

    // Fires when the write operation has completely finished, such as all
    // devices being finalized and resources released.
    static void onWriteComplete();

    // Fires when an error occured during writing, passing the $(ref:ProgressInfo)
    // of the operation at the time the error occured.
    static void onWriteError(ProgressInfo info, DOMString error);

    // Fires when a removable storage device is inserted.
    static void onDeviceInserted(RemovableStorageDevice device);

    // Fires when a removable storage device is removed.
    static void onDeviceRemoved(RemovableStorageDevice device);
  };

};