nsICacheStorage.idl (6776B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 #include "nsISupports.idl" 6 7 interface nsIURI; 8 interface nsICacheEntry; 9 interface nsICacheEntryOpenCallback; 10 interface nsICacheEntryDoomCallback; 11 interface nsICacheStorageVisitor; 12 13 /** 14 * Representation of a cache storage. There can be just-in-mem, 15 * in-mem+on-disk, in-mem+on-disk+app-cache or just a specific 16 * app-cache storage. 17 */ 18 [scriptable, uuid(35d104a6-d252-4fd4-8a56-3c14657cad3b)] 19 interface nsICacheStorage : nsISupports 20 { 21 /** 22 * Placeholder for specifying "no special flags" during open. 23 */ 24 const uint32_t OPEN_NORMALLY = 0; 25 26 /** 27 * Rewrite any existing data when opening a URL. 28 */ 29 const uint32_t OPEN_TRUNCATE = 1 << 0; 30 31 /** 32 * Only open an existing entry. Don't create a new one. 33 */ 34 const uint32_t OPEN_READONLY = 1 << 1; 35 36 /** 37 * Use for first-paint blocking loads. 38 */ 39 const uint32_t OPEN_PRIORITY = 1 << 2; 40 41 /** 42 * Bypass the cache load when write is still in progress. 43 */ 44 const uint32_t OPEN_BYPASS_IF_BUSY = 1 << 3; 45 46 /** 47 * Perform the cache entry check (onCacheEntryCheck invocation) on any thread 48 * for optimal perfomance optimization. If this flag is not specified it is 49 * ensured that onCacheEntryCheck is called on the same thread as respective 50 * asyncOpen has been called. 51 */ 52 const uint32_t CHECK_MULTITHREADED = 1 << 4; 53 54 /** 55 * Don't automatically update any 'last used' metadata of the entry. 56 */ 57 const uint32_t OPEN_SECRETLY = 1 << 5; 58 59 /** 60 * Entry is being opened as part of a service worker interception. Do not 61 * allow the cache to be disabled in this case. 62 */ 63 const uint32_t OPEN_INTERCEPTED = 1 << 6; 64 65 /** 66 * Only open an existing entry which is complete (i.e. not being written) 67 */ 68 const uint32_t OPEN_COMPLETE_ONLY = 1 << 7; 69 70 /** 71 * Asynchronously opens a cache entry for the specified URI. 72 * Result is fetched asynchronously via the callback. 73 * 74 * @param aURI 75 * The URI to search in cache or to open for writing. 76 * @param aIdExtension 77 * Any string that will extend (distinguish) the entry. Two entries 78 * with the same aURI but different aIdExtension will be comletely 79 * different entries. If you don't know what aIdExtension should be 80 * leave it empty. 81 * @param aFlags 82 * OPEN_NORMALLY - open cache entry normally for read and write 83 * OPEN_TRUNCATE - delete any existing entry before opening it 84 * OPEN_READONLY - don't create an entry if there is none 85 * OPEN_PRIORITY - give this request a priority over others 86 * OPEN_BYPASS_IF_BUSY - backward compatibility only, LOAD_BYPASS_LOCAL_CACHE_IF_BUSY 87 * CHECK_MULTITHREADED - onCacheEntryCheck may be called on any thread, consumer 88 * implementation is thread-safe 89 * @param aCallback 90 * The consumer that receives the result. 91 * IMPORTANT: The callback may be called sooner the method returns. 92 */ 93 void asyncOpenURI(in nsIURI aURI, in ACString aIdExtension, 94 in uint32_t aFlags, 95 in nsICacheEntryOpenCallback aCallback); 96 97 /** 98 * Asynchronously opens a cache entry for the specified URI. 99 * Result is fetched asynchronously via the callback. 100 * 101 * @param aURI 102 * The URI to search in cache or to open for writing. 103 * @param aIdExtension 104 * Any string that will extend (distinguish) the entry. Two entries 105 * with the same aURI but different aIdExtension will be comletely 106 * different entries. If you don't know what aIdExtension should be 107 * leave it empty. 108 * @param aFlags 109 * OPEN_NORMALLY - open cache entry normally for read and write 110 * OPEN_TRUNCATE - delete any existing entry before opening it 111 * OPEN_READONLY - don't create an entry if there is none 112 * OPEN_PRIORITY - give this request a priority over others 113 * OPEN_BYPASS_IF_BUSY - backward compatibility only, LOAD_BYPASS_LOCAL_CACHE_IF_BUSY 114 * CHECK_MULTITHREADED - onCacheEntryCheck may be called on any thread, consumer 115 * implementation is thread-safe 116 * @param aCallback 117 * The consumer that receives the result. 118 * IMPORTANT: The callback may be called sooner the method returns. 119 */ 120 void asyncOpenURIString(in ACString aURI, in ACString aIdExtension, 121 in uint32_t aFlags, 122 in nsICacheEntryOpenCallback aCallback); 123 124 /** 125 * Immediately opens a new and empty cache entry in the storage, any existing 126 * entries are immediately doomed. This is similar to the recreate() method 127 * on nsICacheEntry. 128 * 129 * Storage may not implement this method and throw NS_ERROR_NOT_IMPLEMENTED. 130 * In that case consumer must use asyncOpen with OPEN_TRUNCATE flag and get 131 * the new entry via a callback. 132 * 133 * @param aURI @see asyncOpenURI 134 * @param aIdExtension @see asyncOpenURI 135 */ 136 nsICacheEntry openTruncate(in nsIURI aURI, 137 in ACString aIdExtension); 138 139 /** 140 * Synchronously check on existance of an entry. In case of disk entries 141 * this uses information from the cache index. When the index data are not 142 * up to date or index is still building, NS_ERROR_NOT_AVAILABLE is thrown. 143 * The same error may throw any storage implementation that cannot determine 144 * entry state without blocking the caller. 145 */ 146 boolean exists(in nsIURI aURI, in ACString aIdExtension); 147 148 /** 149 * Synchronously check on existance of alternative data and size of the 150 * content. When the index data are not up to date or index is still building, 151 * NS_ERROR_NOT_AVAILABLE is thrown. The same error may throw any storage 152 * implementation that cannot determine entry state without blocking the caller. 153 */ 154 void getCacheIndexEntryAttrs(in nsIURI aURI, 155 in ACString aIdExtension, 156 out boolean aHasAltData, 157 out uint32_t aSizeInKB); 158 /** 159 * Asynchronously removes an entry belonging to the URI from the cache. 160 */ 161 void asyncDoomURI(in nsIURI aURI, in ACString aIdExtension, 162 in nsICacheEntryDoomCallback aCallback); 163 164 /** 165 * Asynchronously removes all cached entries under this storage. 166 * NOTE: Disk storage also evicts memory storage. 167 */ 168 void asyncEvictStorage(in nsICacheEntryDoomCallback aCallback); 169 170 /** 171 * Visits the storage and its entries. 172 * NOTE: Disk storage also visits memory storage. 173 */ 174 void asyncVisitStorage(in nsICacheStorageVisitor aVisitor, 175 in boolean aVisitEntries); 176 177 };