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
7interface nsICacheEntry;
8
9[scriptable, uuid(1fc9fe11-c6ac-4748-94bd-8555a5a12b94)]
10interface nsICacheEntryOpenCallback : nsISupports
11{
12  /**
13   * State of the entry determined by onCacheEntryCheck.
14   *
15   * ENTRY_WANTED - the consumer is interested in the entry, we will pass it.
16   * RECHECK_AFTER_WRITE_FINISHED - the consumer cannot use the entry while data is
17   *    still being written and wants to check it again after the current write is
18   *    finished. This actually prevents concurrent read/write and is used with
19   *    non-resumable HTTP responses.
20   * ENTRY_NEEDS_REVALIDATION - entry needs to be revalidated first with origin server,
21   *    this means the loading channel will decide whether to use the entry content
22   *    as is after it gets a positive response from the server about validity of the
23   *    content ; when a new content needs to be loaded from the server, the loading
24   *    channel opens a new entry with OPEN_TRUNCATE flag which dooms the one
25   *    this check has been made for.
26   * ENTRY_NOT_WANTED - the consumer is not interested in the entry, we will not pass it.
27   */
28  const unsigned long ENTRY_WANTED = 0;
29  const unsigned long RECHECK_AFTER_WRITE_FINISHED = 1;
30  const unsigned long ENTRY_NEEDS_REVALIDATION = 2;
31  const unsigned long ENTRY_NOT_WANTED = 3;
32
33  /**
34   * Callback to perform any validity checks before the entry should be used.
35   * Called before onCacheEntryAvailable callback, depending on the result it
36   * may be called more then one time.
37   *
38   * This callback is ensured to be called on the same thread on which asyncOpenURI
39   * has been called, unless nsICacheStorage.CHECK_MULTITHREADED flag has been specified.
40   * In that case this callback can be invoked on any thread, usually it is the cache I/O
41   * or cache management thread.
42   *
43   * IMPORTANT NOTE:
44   * This callback may be invoked sooner then respective asyncOpenURI call exits.
45   *
46   * @param aEntry
47   *    An entry to examine.  Consumer has a chance to decide whether the
48   *    entry is valid or not.
49   * @return
50   *    State of the entry, see the constants just above.
51   */
52  unsigned long onCacheEntryCheck(in nsICacheEntry aEntry);
53
54  /**
55   * Callback giving actual result of asyncOpenURI.  It may give consumer the cache
56   * entry or a failure result when it's not possible to open it from some reason.
57   * This callback is ensured to be called on the same thread on which asyncOpenURI
58   * has been called.
59   *
60   * IMPORTANT NOTE:
61   * This callback may be invoked sooner then respective asyncOpenURI call exits.
62   *
63   * @param aEntry
64   *    The entry bound to the originally requested URI.
65   * @param aNew
66   *    Whether no data so far has been stored for this entry, i.e. reading
67   *    it will just fail.  When aNew is true, a server request should be
68   *    made and data stored to this new entry.
69   * @param aResult
70   *    Result of the request.  This may be a failure only when one of these
71   *    issues occur:
72   *    - the cache storage service could not be started due to some unexpected
73   *      faulure
74   *    - there is not enough disk space to create new entries
75   */
76  void onCacheEntryAvailable(in nsICacheEntry aEntry,
77                             in boolean aNew,
78                             in nsresult aResult);
79};
80