netwerk/cache/nsICache.idl@a63d609f5ebe
netwerk/cache/nsICache.idl
Thu, 15 Jan 2015 15:55:04 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 15 Jan 2015 15:55:04 +0100
- branch
- TOR_BUG_9701
- changeset 9
- a63d609f5ebe
- permissions
- -rw-r--r--
Back out 97036ab72558 which inappropriately compared turds to third parties.
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include "nsISupports.idl"
9 typedef long nsCacheStoragePolicy;
10 typedef long nsCacheAccessMode;
12 /**
13 * nsICache is a namespace for various cache constants. It does not represent
14 * an actual object.
15 */
16 [scriptable, uuid(d6c67f38-b39a-4582-8a48-4c4f8a56dfd0)]
17 interface nsICache
18 {
19 /**
20 * Access Modes
21 *
22 *
23 * Mode Requested | Not Cached | Cached
24 * ------------------------------------------------------------------------
25 * READ | KEY_NOT_FOUND | NS_OK
26 * | Mode = NONE | Mode = READ
27 * | No Descriptor | Descriptor
28 * ------------------------------------------------------------------------
29 * WRITE | NS_OK | NS_OK (Cache service
30 * | Mode = WRITE | Mode = WRITE dooms existing
31 * | Descriptor | Descriptor cache entry)
32 * ------------------------------------------------------------------------
33 * READ_WRITE | NS_OK | NS_OK
34 * (1st req.) | Mode = WRITE | Mode = READ_WRITE
35 * | Descriptor | Descriptor
36 * ------------------------------------------------------------------------
37 * READ_WRITE | N/A | NS_OK
38 * (Nth req.) | | Mode = READ
39 * | | Descriptor
40 * ------------------------------------------------------------------------
41 *
42 *
43 * Access Requested:
44 *
45 * READ - I only want to READ, if there isn't an entry just fail
46 * WRITE - I have something new I want to write into the cache, make
47 * me a new entry and doom the old one, if any.
48 * READ_WRITE - I want to READ, but I'm willing to update an existing
49 * entry if necessary, or create a new one if none exists.
50 *
51 *
52 * Access Granted:
53 *
54 * NONE - No descriptor is provided. You get zilch. Nada. Nothing.
55 * READ - You can READ from this descriptor.
56 * WRITE - You must WRITE to this descriptor because the cache entry
57 * was just created for you.
58 * READ_WRITE - You can READ the descriptor to determine if it's valid,
59 * you may WRITE if it needs updating.
60 *
61 *
62 * Comments:
63 *
64 * If you think that you might need to modify cached data or meta data,
65 * then you must open a cache entry requesting WRITE access. Only one
66 * cache entry descriptor, per cache entry, will be granted WRITE access.
67 *
68 * Usually, you will request READ_WRITE access in order to first test the
69 * meta data and informational fields to determine if a write (ie. going
70 * to the net) may actually be necessary. If you determine that it is
71 * not, then you would mark the cache entry as valid (using MarkValid) and
72 * then simply read the data from the cache.
73 *
74 * A descriptor granted WRITE access has exclusive access to the cache
75 * entry up to the point at which it marks it as valid. Once the cache
76 * entry has been "validated", other descriptors with READ access may be
77 * opened to the cache entry.
78 *
79 * If you make a request for READ_WRITE access to a cache entry, the cache
80 * service will downgrade your access to READ if there is already a
81 * cache entry descriptor open with WRITE access.
82 *
83 * If you make a request for only WRITE access to a cache entry and another
84 * descriptor with WRITE access is currently open, then the existing cache
85 * entry will be 'doomed', and you will be given a descriptor (with WRITE
86 * access only) to a new cache entry.
87 *
88 */
89 const nsCacheAccessMode ACCESS_NONE = 0;
90 const nsCacheAccessMode ACCESS_READ = 1;
91 const nsCacheAccessMode ACCESS_WRITE = 2;
92 const nsCacheAccessMode ACCESS_READ_WRITE = 3;
94 /**
95 * Storage Policy
96 *
97 * The storage policy of a cache entry determines the device(s) to which
98 * it belongs. See nsICacheSession and nsICacheEntryDescriptor for more
99 * details.
100 *
101 * STORE_ANYWHERE - Allows the cache entry to be stored in any device.
102 * The cache service decides which cache device to use
103 * based on "some resource management calculation."
104 * STORE_IN_MEMORY - Requires the cache entry to reside in non-persistent
105 * storage (ie. typically in system RAM).
106 * STORE_ON_DISK - Requires the cache entry to reside in persistent
107 * storage (ie. typically on a system's hard disk).
108 * STORE_OFFLINE - Requires the cache entry to reside in persistent,
109 * reliable storage for offline use.
110 */
111 const nsCacheStoragePolicy STORE_ANYWHERE = 0;
112 const nsCacheStoragePolicy STORE_IN_MEMORY = 1;
113 const nsCacheStoragePolicy STORE_ON_DISK = 2;
114 // value 3 was used by STORE_ON_DISK_AS_FILE which was removed
115 const nsCacheStoragePolicy STORE_OFFLINE = 4;
117 /**
118 * All entries for a cache session are stored as streams of data or
119 * as objects. These constant my be used to specify the type of entries
120 * when calling nsICacheService::CreateSession().
121 */
122 const long NOT_STREAM_BASED = 0;
123 const long STREAM_BASED = 1;
125 /**
126 * The synchronous OpenCacheEntry() may be blocking or non-blocking. If a cache entry is
127 * waiting to be validated by another cache descriptor (so no new cache descriptors for that
128 * key can be created, OpenCacheEntry() will return NS_ERROR_CACHE_WAIT_FOR_VALIDATION in
129 * non-blocking mode. In blocking mode, it will wait until the cache entry for the key has
130 * been validated or doomed. If the cache entry is validated, then a descriptor for that
131 * entry will be created and returned. If the cache entry was doomed, then a descriptor
132 * will be created for a new cache entry for the key.
133 */
134 const long NON_BLOCKING = 0;
135 const long BLOCKING = 1;
137 /**
138 * Constant meaning no expiration time.
139 */
140 const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;
141 };
