netwerk/cache/nsICacheEntryDescriptor.idl@a63d609f5ebe
netwerk/cache/nsICacheEntryDescriptor.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 "nsICacheVisitor.idl"
8 #include "nsICache.idl"
10 interface nsISimpleEnumerator;
11 interface nsICacheListener;
12 interface nsIInputStream;
13 interface nsIOutputStream;
14 interface nsIFile;
15 interface nsICacheMetaDataVisitor;
18 [scriptable, uuid(90b17d31-46aa-4fb1-a206-473c966cbc18)]
19 interface nsICacheEntryDescriptor : nsICacheEntryInfo
20 {
21 /**
22 * Set the time at which the cache entry should be considered invalid (in
23 * seconds since the Epoch).
24 */
25 void setExpirationTime(in uint32_t expirationTime);
27 /**
28 * Set the cache entry data size. This will fail if the cache entry
29 * IS stream based.
30 */
31 void setDataSize(in unsigned long size);
33 /**
34 * Open blocking input stream to cache data. This will fail if the cache
35 * entry IS NOT stream based. Use the stream transport service to
36 * asynchronously read this stream on a background thread. The returned
37 * stream MAY implement nsISeekableStream.
38 *
39 * @param offset
40 * read starting from this offset into the cached data. an offset
41 * beyond the end of the stream has undefined consequences.
42 *
43 * @return blocking, unbuffered input stream.
44 */
45 nsIInputStream openInputStream(in unsigned long offset);
47 /**
48 * Open blocking output stream to cache data. This will fail if the cache
49 * entry IS NOT stream based. Use the stream transport service to
50 * asynchronously write to this stream on a background thread. The returned
51 * stream MAY implement nsISeekableStream.
52 *
53 * If opening an output stream to existing cached data, the data will be
54 * truncated to the specified offset.
55 *
56 * @param offset
57 * write starting from this offset into the cached data. an offset
58 * beyond the end of the stream has undefined consequences.
59 *
60 * @return blocking, unbuffered output stream.
61 */
62 nsIOutputStream openOutputStream(in unsigned long offset);
64 /**
65 * Get/set the cache data element. This will fail if the cache entry
66 * IS stream based. The cache entry holds a strong reference to this
67 * object. The object will be released when the cache entry is destroyed.
68 */
69 attribute nsISupports cacheElement;
71 /**
72 * Stores the Content-Length specified in the HTTP header for this
73 * entry. Checked before we write to the cache entry, to prevent ever
74 * taking up space in the cache for an entry that we know up front
75 * is going to have to be evicted anyway. See bug 588507.
76 */
77 attribute int64_t predictedDataSize;
79 /**
80 * Get the access granted to this descriptor. See nsICache.idl for the
81 * definitions of the access modes and a thorough description of their
82 * corresponding meanings.
83 */
84 readonly attribute nsCacheAccessMode accessGranted;
86 /**
87 * Get/set the storage policy of the cache entry. See nsICache.idl for
88 * the definitions of the storage policies.
89 */
90 attribute nsCacheStoragePolicy storagePolicy;
92 /**
93 * Get the disk file associated with the cache entry.
94 */
95 readonly attribute nsIFile file;
97 /**
98 * Get/set security info on the cache entry for this descriptor. This fails
99 * if the storage policy is not STORE_IN_MEMORY.
100 */
101 attribute nsISupports securityInfo;
103 /**
104 * Get the size of the cache entry data, as stored. This may differ
105 * from the entry's dataSize, if the entry is compressed.
106 */
107 readonly attribute unsigned long storageDataSize;
109 /**
110 * Doom the cache entry this descriptor references in order to slate it for
111 * removal. Once doomed a cache entry cannot be undoomed.
112 *
113 * A descriptor with WRITE access can doom the cache entry and choose to
114 * fail pending requests. This means that pending requests will not get
115 * a cache descriptor. This is meant as a tool for clients that wish to
116 * instruct pending requests to skip the cache.
117 */
118 void doom();
119 void doomAndFailPendingRequests(in nsresult status);
121 /**
122 * Asynchronously doom an entry. Listener will be notified about the status
123 * of the operation. Null may be passed if caller doesn't care about the
124 * result.
125 */
126 void asyncDoom(in nsICacheListener listener);
128 /**
129 * A writer must validate this cache object before any readers are given
130 * a descriptor to the object.
131 */
132 void markValid();
134 /**
135 * Explicitly close the descriptor (optional).
136 */
138 void close();
140 /**
141 * Methods for accessing meta data. Meta data is a table of key/value
142 * string pairs. The strings do not have to conform to any particular
143 * charset, but they must be null terminated.
144 */
145 string getMetaDataElement(in string key);
146 void setMetaDataElement(in string key, in string value);
148 /**
149 * Visitor will be called with key/value pair for each meta data element.
150 */
151 void visitMetaData(in nsICacheMetaDataVisitor visitor);
152 };
156 [scriptable, uuid(22f9a49c-3cf8-4c23-8006-54efb11ac562)]
157 interface nsICacheMetaDataVisitor : nsISupports
158 {
159 /**
160 * Called for each key/value pair in the meta data for a cache entry
161 */
162 boolean visitMetaDataElement(in string key,
163 in string value);
164 };
