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