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 nsICacheEntry;
michael@0: interface nsIApplicationCache;
michael@0: 
michael@0: [scriptable, uuid(1fc9fe11-c6ac-4748-94bd-8555a5a12b94)]
michael@0: interface nsICacheEntryOpenCallback : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * State of the entry determined by onCacheEntryCheck.
michael@0:    *
michael@0:    * ENTRY_WANTED - the consumer is interested in the entry, we will pass it.
michael@0:    * RECHECK_AFTER_WRITE_FINISHED - the consumer cannot use the entry while data is
michael@0:    *    still being written and wants to check it again after the current write is
michael@0:    *    finished. This actually prevents concurrent read/write and is used with
michael@0:    *    non-resumable HTTP responses.
michael@0:    * ENTRY_NEEDS_REVALIDATION - entry needs to be revalidated first with origin server,
michael@0:    *    this means the loading channel will decide whether to use the entry content
michael@0:    *    as is after it gets a positive response from the server about validity of the
michael@0:    *    content ; when a new content needs to be loaded from the server, the loading
michael@0:    *    channel opens a new entry with OPEN_TRUNCATE flag which dooms the one
michael@0:    *    this check has been made for.
michael@0:    * ENTRY_NOT_WANTED - the consumer is not interested in the entry, we will not pass it.
michael@0:    */
michael@0:   const unsigned long ENTRY_WANTED = 0;
michael@0:   const unsigned long RECHECK_AFTER_WRITE_FINISHED = 1;
michael@0:   const unsigned long ENTRY_NEEDS_REVALIDATION = 2;
michael@0:   const unsigned long ENTRY_NOT_WANTED = 3;
michael@0: 
michael@0:   /**
michael@0:    * Callback to perform any validity checks before the entry should be used.
michael@0:    * Called before onCacheEntryAvailable callback, depending on the result it
michael@0:    * may be called more then one time.
michael@0:    *
michael@0:    * This callback is ensured to be called on the same thread on which asyncOpenURI
michael@0:    * has been called, unless nsICacheStorage.CHECK_MULTITHREADED flag has been specified.
michael@0:    * In that case this callback can be invoked on any thread, usually it is the cache I/O
michael@0:    * or cache management thread.
michael@0:    *
michael@0:    * IMPORTANT NOTE: 
michael@0:    * This callback may be invoked sooner then respective asyncOpenURI call exits.
michael@0:    *
michael@0:    * @param aEntry
michael@0:    *    An entry to examine.  Consumer has a chance to decide whether the
michael@0:    *    entry is valid or not.
michael@0:    * @param aApplicationCache
michael@0:    *    Optional, application cache the entry has been found in, if any.
michael@0:    * @return
michael@0:    *    State of the entry, see the constants just above.
michael@0:    */
michael@0:   unsigned long onCacheEntryCheck(in nsICacheEntry aEntry,
michael@0:                                   in nsIApplicationCache aApplicationCache);
michael@0: 
michael@0:   /**
michael@0:    * Callback giving actual result of asyncOpenURI.  It may give consumer the cache 
michael@0:    * entry or a failure result when it's not possible to open it from some reason.
michael@0:    * This callback is ensured to be called on the same thread on which asyncOpenURI
michael@0:    * has been called.
michael@0:    *
michael@0:    * IMPORTANT NOTE: 
michael@0:    * This callback may be invoked sooner then respective asyncOpenURI call exits.
michael@0:    *
michael@0:    * @param aEntry
michael@0:    *    The entry bound to the originally requested URI.  May be null when
michael@0:    *    loading from a particular application cache and the URI has not
michael@0:    *    been found in that application cache.
michael@0:    * @param aNew
michael@0:    *    Whether no data so far has been stored for this entry, i.e. reading
michael@0:    *    it will just fail.  When aNew is true, a server request should be
michael@0:    *    made and data stored to this new entry.
michael@0:    * @param aApplicationCache
michael@0:    *    When an entry had been found in an application cache, this is the
michael@0:    *    given application cache.  It should be associated with the loading
michael@0:    *    channel.
michael@0:    * @param aResult
michael@0:    *    Result of the request.  This may be a failure only when one of these
michael@0:    *    issues occur:
michael@0:    *    - the cache storage service could not be started due to some unexpected
michael@0:    *      faulure
michael@0:    *    - there is not enough disk space to create new entries
michael@0:    *    - cache entry was not found in a given application cache
michael@0:    */
michael@0:   void onCacheEntryAvailable(in nsICacheEntry aEntry,
michael@0:                              in boolean aNew,
michael@0:                              in nsIApplicationCache aApplicationCache,
michael@0:                              in nsresult aResult);
michael@0: };