1 // Copyright (c) 2012 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.fileSystem</code> API to create, read, navigate, 6 // and write to the user's local file system. With this API, Chrome Apps can 7 // read and write to a user-selected location. For example, a text editor app 8 // can use the API to read and write local documents. All failures are notified 9 // via chrome.runtime.lastError. 10 namespace fileSystem { 11 dictionary AcceptOption { 12 // This is the optional text description for this option. If not present, 13 // a description will be automatically generated; typically containing an 14 // expanded list of valid extensions (e.g. "text/html" may expand to 15 // "*.html, *.htm"). 16 DOMString? description; 17 18 // Mime-types to accept, e.g. "image/jpeg" or "audio/*". One of mimeTypes or 19 // extensions must contain at least one valid element. 20 DOMString[]? mimeTypes; 21 22 // Extensions to accept, e.g. "jpg", "gif", "crx". 23 DOMString[]? extensions; 24 }; 25 26 enum ChooseEntryType { 27 28 // Prompts the user to open an existing file and returns a FileEntry on 29 // success. From Chrome 31 onwards, the FileEntry will be writable if the 30 // application has the 'write' permission under 'fileSystem'; otherwise, the 31 // FileEntry will be read-only. 32 openFile, 33 34 // Prompts the user to open an existing file and returns a writable 35 // FileEntry on success. Calls using this type will fail with a runtime 36 // error if the application doesn't have the 'write' permission under 37 // 'fileSystem'. 38 openWritableFile, 39 40 // Prompts the user to open an existing file or a new file and returns a 41 // writable FileEntry on success. Calls using this type will fail with a 42 // runtime error if the application doesn't have the 'write' permission 43 // under 'fileSystem'. 44 saveFile, 45 46 // Prompts the user to open a directory and returns a DirectoryEntry on 47 // success. Calls using this type will fail with a runtime error if the 48 // application doesn't have the 'directory' permission under 'fileSystem'. 49 // If the application has the 'write' permission under 'fileSystem', the 50 // returned DirectoryEntry will be writable; otherwise it will be read-only. 51 // New in Chrome 31. 52 openDirectory 53 }; 54 55 dictionary ChooseEntryOptions { 56 // Type of the prompt to show. The default is 'openFile'. 57 ChooseEntryType? type; 58 59 // The suggested file name that will be presented to the user as the 60 // default name to read or write. This is optional. 61 DOMString? suggestedName; 62 63 // The optional list of accept options for this file opener. Each option 64 // will be presented as a unique group to the end-user. 65 AcceptOption[]? accepts; 66 67 // Whether to accept all file types, in addition to the options specified 68 // in the accepts argument. The default is true. If the accepts field is 69 // unset or contains no valid entries, this will always be reset to true. 70 boolean? acceptsAllTypes; 71 72 // Whether to accept multiple files. This is only supported for openFile and 73 // openWritableFile. The callback to chooseEntry will be called with a list 74 // of entries if this is set to true. Otherwise it will be called with a 75 // single Entry. 76 boolean? acceptsMultiple; 77 }; 78 callback GetDisplayPathCallback = void (DOMString displayPath); 79 callback EntryCallback = void ([instanceOf=Entry] object entry); 80 callback EntriesCallback = void ( 81 [instanceOf=Entry] optional object entry, 82 [instanceOf=FileEntry] optional object[] fileEntries); 83 callback IsWritableCallback = void (boolean isWritable); 84 callback IsRestorableCallback = void (boolean isRestorable); 85 86 interface Functions { 87 // Get the display path of an Entry object. The display path is based on 88 // the full path of the file or directory on the local file system, but may 89 // be made more readable for display purposes. 90 static void getDisplayPath([instanceOf=Entry] object entry, 91 GetDisplayPathCallback callback); 92 93 // Get a writable Entry from another Entry. This call will fail with a 94 // runtime error if the application does not have the 'write' permission 95 // under 'fileSystem'. If entry is a DirectoryEntry, this call will fail if 96 // the application does not have the 'directory' permission under 97 // 'fileSystem'. 98 static void getWritableEntry([instanceOf=Entry] object entry, 99 EntryCallback callback); 100 101 // Gets whether this Entry is writable or not. 102 static void isWritableEntry([instanceOf=Entry] object entry, 103 IsWritableCallback callback); 104 105 // Ask the user to choose a file or directory. 106 static void chooseEntry(optional ChooseEntryOptions options, 107 EntriesCallback callback); 108 109 // Returns the file entry with the given id if it can be restored. This call 110 // will fail with a runtime error otherwise. This method is new in Chrome 111 // 31. 112 static void restoreEntry(DOMString id, EntryCallback callback); 113 114 // Returns whether the app has permission to restore the entry with the 115 // given id. This method is new in Chrome 31. 116 static void isRestorable(DOMString id, IsRestorableCallback callback); 117 118 // Returns an id that can be passed to restoreEntry to regain access to a 119 // given file entry. Only the 500 most recently used entries are retained, 120 // where calls to retainEntry and restoreEntry count as use. If the app has 121 // the 'retainEntries' permission under 'fileSystem', entries are retained 122 // indefinitely. Otherwise, entries are retained only while the app is 123 // running and across restarts. This method is new in Chrome 31. 124 static DOMString retainEntry([instanceOf=Entry] object entry); 125 }; 126 }; 127
