summaryrefslogtreecommitdiffstats
path: root/netwerk/cache2/nsICacheStorage.idl
blob: 8169c9b730cf48c87a2193903ed898467f43c11d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIURI;
interface nsICacheEntry;
interface nsICacheEntryOpenCallback;
interface nsICacheEntryDoomCallback;
interface nsICacheStorageVisitor;

/**
 * Representation of a cache storage. There can be just-in-mem,
 * in-mem+on-disk, in-mem+on-disk+app-cache or just a specific
 * app-cache storage.
 */
[scriptable, uuid(35d104a6-d252-4fd4-8a56-3c14657cad3b)]
interface nsICacheStorage : nsISupports
{
  /**
   * Placeholder for specifying "no special flags" during open.
   */
  const uint32_t OPEN_NORMALLY = 0;

  /**
   * Rewrite any existing data when opening a URL.
   */
  const uint32_t OPEN_TRUNCATE = 1 << 0;

  /**
   * Only open an existing entry.  Don't create a new one.
   */
  const uint32_t OPEN_READONLY = 1 << 1;

  /**
   * Use for first-paint blocking loads.
   */
  const uint32_t OPEN_PRIORITY = 1 << 2;

  /**
   * Bypass the cache load when write is still in progress.
   */
  const uint32_t OPEN_BYPASS_IF_BUSY = 1 << 3;

  /**
   * Perform the cache entry check (onCacheEntryCheck invocation) on any thread
   * for optimal perfomance optimization.  If this flag is not specified it is
   * ensured that onCacheEntryCheck is called on the same thread as respective
   * asyncOpen has been called.
   */
  const uint32_t CHECK_MULTITHREADED = 1 << 4;

  /**
   * Don't automatically update any 'last used' metadata of the entry.
   */
  const uint32_t OPEN_SECRETLY = 1 << 5;

  /**
   * Entry is being opened as part of a service worker interception.  Do not
   * allow the cache to be disabled in this case.
   */
  const uint32_t OPEN_INTERCEPTED = 1 << 6;

  /**
   * Asynchronously opens a cache entry for the specified URI.
   * Result is fetched asynchronously via the callback.
   *
   * @param aURI
   *    The URI to search in cache or to open for writting.
   * @param aIdExtension
   *    Any string that will extend (distinguish) the entry.  Two entries
   *    with the same aURI but different aIdExtension will be comletely
   *    different entries.  If you don't know what aIdExtension should be
   *    leave it empty.
   * @param aFlags
   *    OPEN_NORMALLY - open cache entry normally for read and write
   *    OPEN_TRUNCATE - delete any existing entry before opening it
   *    OPEN_READONLY - don't create an entry if there is none
   *    OPEN_PRIORITY - give this request a priority over others
   *    OPEN_BYPASS_IF_BUSY - backward compatibility only, LOAD_BYPASS_LOCAL_CACHE_IF_BUSY
   *    CHECK_MULTITHREADED - onCacheEntryCheck may be called on any thread, consumer
   *                          implementation is thread-safe
   * @param aCallback
   *    The consumer that receives the result.
   *    IMPORTANT: The callback may be called sooner the method returns.
   */
  void asyncOpenURI(in nsIURI aURI, in ACString aIdExtension,
                    in uint32_t aFlags,
                    in nsICacheEntryOpenCallback aCallback);

  /**
   * Immediately opens a new and empty cache entry in the storage, any existing
   * entries are immediately doomed.  This is similar to the recreate() method
   * on nsICacheEntry.
   *
   * Storage may not implement this method and throw NS_ERROR_NOT_IMPLEMENTED.
   * In that case consumer must use asyncOpen with OPEN_TRUNCATE flag and get
   * the new entry via a callback.
   *
   * @param aURI @see asyncOpenURI
   * @param aIdExtension @see asyncOpenURI
   */
  nsICacheEntry openTruncate(in nsIURI aURI,
                             in ACString aIdExtension);

  /**
   * Synchronously check on existance of an entry.  In case of disk entries
   * this uses information from the cache index.  When the index data are not
   * up to date or index is still building, NS_ERROR_NOT_AVAILABLE is thrown.
   * The same error may throw any storage implementation that cannot determine
   * entry state without blocking the caller.
   */
  boolean exists(in nsIURI aURI, in ACString aIdExtension);

  /**
   * Synchronously check on existance of alternative data and size of the
   * content. When the index data are not up to date or index is still building,
   * NS_ERROR_NOT_AVAILABLE is thrown. The same error may throw any storage
   * implementation that cannot determine entry state without blocking the caller.
   */
  void getCacheIndexEntryAttrs(in nsIURI aURI,
                               in ACString aIdExtension,
                               out bool aHasAltData,
                               out uint32_t aSizeInKB);
  /**
   * Asynchronously removes an entry belonging to the URI from the cache.
   */
  void asyncDoomURI(in nsIURI aURI, in ACString aIdExtension,
                    in nsICacheEntryDoomCallback aCallback);

  /**
   * Asynchronously removes all cached entries under this storage.
   * NOTE: Disk storage also evicts memory storage.
   */
  void asyncEvictStorage(in nsICacheEntryDoomCallback aCallback);

  /**
   * Visits the storage and its entries.
   * NOTE: Disk storage also visits memory storage.
   */
  void asyncVisitStorage(in nsICacheStorageVisitor aVisitor,
                         in boolean aVisitEntries);

};