michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: interface nsICacheEntryOpenCallback;
michael@0: interface nsICacheEntryDoomCallback;
michael@0: interface nsICacheStorageVisitor;
michael@0: 
michael@0: /**
michael@0:  * Representation of a cache storage. There can be just-in-mem,
michael@0:  * in-mem+on-disk, in-mem+on-disk+app-cache or just a specific
michael@0:  * app-cache storage.
michael@0:  */
michael@0: [scriptable, uuid(d983ba0c-433f-4017-abc1-93af737c82e4)]
michael@0: interface nsICacheStorage : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Placeholder for specifying "no special flags" during open.
michael@0:    */
michael@0:   const uint32_t OPEN_NORMALLY = 0;
michael@0: 
michael@0:   /**
michael@0:    * Rewrite any existing data when opening a URL.
michael@0:    */
michael@0:   const uint32_t OPEN_TRUNCATE = 1 << 0;
michael@0: 
michael@0:   /**
michael@0:    * Only open an existing entry.  Don't create a new one.
michael@0:    */
michael@0:   const uint32_t OPEN_READONLY = 1 << 1;
michael@0: 
michael@0:   /**
michael@0:    * Use for first-paint blocking loads.
michael@0:    */
michael@0:   const uint32_t OPEN_PRIORITY = 1 << 2;
michael@0: 
michael@0:   /**
michael@0:    * Bypass the cache load when write is still in progress.
michael@0:    */
michael@0:   const uint32_t OPEN_BYPASS_IF_BUSY = 1 << 3;
michael@0: 
michael@0:   /**
michael@0:    * Perform the cache entry check (onCacheEntryCheck invocation) on any thread 
michael@0:    * for optimal perfomance optimization.  If this flag is not specified it is
michael@0:    * ensured that onCacheEntryCheck is called on the same thread as respective 
michael@0:    * asyncOpen has been called.
michael@0:    */
michael@0:   const uint32_t CHECK_MULTITHREADED = 1 << 4;
michael@0: 
michael@0:   /**
michael@0:    * Asynchronously opens a cache entry for the specified URI.
michael@0:    * Result is fetched asynchronously via the callback.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *    The URI to search in cache or to open for writting.
michael@0:    * @param aIdExtension
michael@0:    *    Any string that will extend (distinguish) the entry.  Two entries
michael@0:    *    with the same aURI but different aIdExtension will be comletely
michael@0:    *    different entries.  If you don't know what aIdExtension should be
michael@0:    *    leave it empty.
michael@0:    * @param aFlags
michael@0:    *    OPEN_NORMALLY - open cache entry normally for read and write
michael@0:    *    OPEN_TRUNCATE - delete any existing entry before opening it
michael@0:    *    OPEN_READONLY - don't create an entry if there is none
michael@0:    *    OPEN_PRIORITY - give this request a priority over others
michael@0:    *    OPEN_BYPASS_IF_BUSY - backward compatibility only, LOAD_BYPASS_LOCAL_CACHE_IF_BUSY
michael@0:    *    CHECK_MULTITHREADED - onCacheEntryCheck may be called on any thread, consumer 
michael@0:    *                          implementation is thread-safe
michael@0:    * @param aCallback
michael@0:    *    The consumer that receives the result.
michael@0:    *    IMPORTANT: The callback may be called sooner the method returns.
michael@0:    */
michael@0:   void asyncOpenURI(in nsIURI aURI, in ACString aIdExtension,
michael@0:                     in uint32_t aFlags,
michael@0:                     in nsICacheEntryOpenCallback aCallback);
michael@0: 
michael@0:   /**
michael@0:    * Asynchronously removes an entry belonging to the URI from the cache.
michael@0:    */
michael@0:   void asyncDoomURI(in nsIURI aURI, in ACString aIdExtension,
michael@0:                     in nsICacheEntryDoomCallback aCallback);
michael@0: 
michael@0:   /**
michael@0:    * Asynchronously removes all cached entries under this storage.
michael@0:    * NOTE: Disk storage also evicts memory storage.
michael@0:    */
michael@0:   void asyncEvictStorage(in nsICacheEntryDoomCallback aCallback);
michael@0: 
michael@0:   /**
michael@0:    * Visits the storage and its entries.
michael@0:    * NOTE: Disk storage also visits memory storage.
michael@0:    */
michael@0:   void asyncVisitStorage(in nsICacheStorageVisitor aVisitor,
michael@0:                          in boolean aVisitEntries);
michael@0: };