netwerk/cache2/nsICacheEntry.idl@7e26c7da4463
netwerk/cache2/nsICacheEntry.idl
Wed, 31 Dec 2014 06:55:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:50 +0100
- changeset 2
- 7e26c7da4463
- permissions
- -rw-r--r--
Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2
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/. */
5 #include "nsISupports.idl"
7 interface nsIInputStream;
8 interface nsIOutputStream;
9 interface nsICacheEntryDoomCallback;
11 // ************************ REMOVE **********************
12 typedef long nsCacheAccessMode;
13 typedef long nsCacheStoragePolicy;
15 interface nsICacheListener;
16 interface nsIFile;
17 interface nsICacheMetaDataVisitor;
19 [scriptable, uuid(3058bf1e-5116-41cf-826b-e6981308d414)]
20 interface nsICacheEntry : nsISupports
21 {
22 /**
23 * Placeholder for the initial value of expiration time.
24 */
25 const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;
27 /**
28 * Get the key identifying the cache entry.
29 */
30 readonly attribute ACString key;
32 /**
33 * Whether the entry is memory/only or persisted to disk.
34 * Note: private browsing entries are reported as persistent for consistency
35 * while are not actually persisted to disk.
36 */
37 readonly attribute boolean persistent;
39 /**
40 * Get the number of times the cache entry has been opened.
41 */
42 readonly attribute long fetchCount;
44 /**
45 * Get the last time the cache entry was opened (in seconds since the Epoch).
46 */
47 readonly attribute uint32_t lastFetched;
49 /**
50 * Get the last time the cache entry was modified (in seconds since the Epoch).
51 */
52 readonly attribute uint32_t lastModified;
54 /**
55 * Get the expiration time of the cache entry (in seconds since the Epoch).
56 */
57 readonly attribute uint32_t expirationTime;
59 /**
60 * Set the time at which the cache entry should be considered invalid (in
61 * seconds since the Epoch).
62 */
63 void setExpirationTime(in uint32_t expirationTime);
65 /**
66 * Open blocking input stream to cache data. Use the stream transport
67 * service to asynchronously read this stream on a background thread.
68 * The returned stream MAY implement nsISeekableStream.
69 *
70 * @param offset
71 * read starting from this offset into the cached data. an offset
72 * beyond the end of the stream has undefined consequences.
73 *
74 * @return non-blocking, buffered input stream.
75 */
76 nsIInputStream openInputStream(in long long offset);
78 /**
79 * Open non-blocking output stream to cache data. The returned stream
80 * MAY implement nsISeekableStream.
81 *
82 * If opening an output stream to existing cached data, the data will be
83 * truncated to the specified offset.
84 *
85 * @param offset
86 * write starting from this offset into the cached data. an offset
87 * beyond the end of the stream has undefined consequences.
88 *
89 * @return blocking, buffered output stream.
90 */
91 nsIOutputStream openOutputStream(in long long offset);
93 /**
94 * Stores the Content-Length specified in the HTTP header for this
95 * entry. Checked before we write to the cache entry, to prevent ever
96 * taking up space in the cache for an entry that we know up front
97 * is going to have to be evicted anyway. See bug 588507.
98 */
99 attribute int64_t predictedDataSize;
101 /**
102 * Get/set security info on the cache entry for this descriptor.
103 */
104 attribute nsISupports securityInfo;
106 /**
107 * Get the size of the cache entry data, as stored. This may differ
108 * from the entry's dataSize, if the entry is compressed.
109 */
110 readonly attribute unsigned long storageDataSize;
112 /**
113 * Asynchronously doom an entry. Listener will be notified about the status
114 * of the operation. Null may be passed if caller doesn't care about the
115 * result.
116 */
117 void asyncDoom(in nsICacheEntryDoomCallback listener);
119 /**
120 * Methods for accessing meta data. Meta data is a table of key/value
121 * string pairs. The strings do not have to conform to any particular
122 * charset, but they must be null terminated.
123 */
124 string getMetaDataElement(in string key);
125 void setMetaDataElement(in string key, in string value);
127 /**
128 * Claims that all metadata on this entry are up-to-date and this entry
129 * now can be delivered to other waiting consumers.
130 *
131 * We need such method since metadata must be delivered synchronously.
132 */
133 void metaDataReady();
135 /**
136 * Called by consumer upon 304/206 response from the server. This marks
137 * the entry content as positively revalidated.
138 * Consumer uses this method after the consumer has returned ENTRY_NEEDS_REVALIDATION
139 * result from onCacheEntryCheck and after successfull revalidation with the server.
140 */
141 void setValid();
143 /**
144 * Doom this entry and open a new, empty, entry for write. Consumer has
145 * to exchange the entry this method is called on for the newly created.
146 * Used on 200 responses to conditional requests.
147 *
148 * @param aMemoryOnly
149 * - whether the entry is to be created as memory/only regardless how
150 * the entry being recreated persistence is set
151 * @returns
152 * - an entry that can be used to write to
153 * @throws
154 * - NS_ERROR_NOT_AVAILABLE when the entry cannot be from some reason
155 * recreated for write
156 */
157 nsICacheEntry recreate([optional] in boolean aMemoryOnly);
159 /**
160 * Returns the length of data this entry holds.
161 * @throws
162 * NS_ERROR_IN_PROGRESS when the write is still in progress.
163 */
164 readonly attribute long long dataSize;
166 /****************************************************************************
167 * The following methods might be added to some nsICacheEntryInternal
168 * interface since we want to remove them as soon as the old cache backend is
169 * completely removed.
170 */
172 /**
173 * @deprecated
174 * FOR BACKWARD COMPATIBILITY ONLY
175 * When the old cache backend is eventually removed, this method
176 * can be removed too.
177 *
178 * In the new backend: this method is no-op
179 * In the old backend: this method delegates to nsICacheEntryDescriptor.close()
180 */
181 void close();
183 /**
184 * @deprecated
185 * FOR BACKWARD COMPATIBILITY ONLY
186 * Marks the entry as valid so that others can use it and get only readonly
187 * access when the entry is held by the 1st writer.
188 */
189 void markValid();
191 /**
192 * @deprecated
193 * FOR BACKWARD COMPATIBILITY ONLY
194 * Marks the entry as valid when write access is acquired.
195 */
196 void maybeMarkValid();
198 /**
199 * @deprecated
200 * FOR BACKWARD COMPATIBILITY ONLY / KINDA HACK
201 * @param aWriteAllowed
202 * Consumer indicates whether write to the entry is allowed for it.
203 * Depends on implementation how the flag is handled.
204 * @returns
205 * true when write access is acquired for this entry,
206 * false otherwise
207 */
208 boolean hasWriteAccess(in boolean aWriteAllowed);
209 };
