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. However, it can fail and call the callback with 105 // an error. 106 // 107 // |storageUnitId|: The identifier of the storage unit to wipe 108 // |callback|: A callback which is called when the operation is complete. 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 140
