1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/cache2/nsICacheEntry.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,209 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIInputStream;
1.11 +interface nsIOutputStream;
1.12 +interface nsICacheEntryDoomCallback;
1.13 +
1.14 +// ************************ REMOVE **********************
1.15 +typedef long nsCacheAccessMode;
1.16 +typedef long nsCacheStoragePolicy;
1.17 +
1.18 +interface nsICacheListener;
1.19 +interface nsIFile;
1.20 +interface nsICacheMetaDataVisitor;
1.21 +
1.22 +[scriptable, uuid(3058bf1e-5116-41cf-826b-e6981308d414)]
1.23 +interface nsICacheEntry : nsISupports
1.24 +{
1.25 + /**
1.26 + * Placeholder for the initial value of expiration time.
1.27 + */
1.28 + const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;
1.29 +
1.30 + /**
1.31 + * Get the key identifying the cache entry.
1.32 + */
1.33 + readonly attribute ACString key;
1.34 +
1.35 + /**
1.36 + * Whether the entry is memory/only or persisted to disk.
1.37 + * Note: private browsing entries are reported as persistent for consistency
1.38 + * while are not actually persisted to disk.
1.39 + */
1.40 + readonly attribute boolean persistent;
1.41 +
1.42 + /**
1.43 + * Get the number of times the cache entry has been opened.
1.44 + */
1.45 + readonly attribute long fetchCount;
1.46 +
1.47 + /**
1.48 + * Get the last time the cache entry was opened (in seconds since the Epoch).
1.49 + */
1.50 + readonly attribute uint32_t lastFetched;
1.51 +
1.52 + /**
1.53 + * Get the last time the cache entry was modified (in seconds since the Epoch).
1.54 + */
1.55 + readonly attribute uint32_t lastModified;
1.56 +
1.57 + /**
1.58 + * Get the expiration time of the cache entry (in seconds since the Epoch).
1.59 + */
1.60 + readonly attribute uint32_t expirationTime;
1.61 +
1.62 + /**
1.63 + * Set the time at which the cache entry should be considered invalid (in
1.64 + * seconds since the Epoch).
1.65 + */
1.66 + void setExpirationTime(in uint32_t expirationTime);
1.67 +
1.68 + /**
1.69 + * Open blocking input stream to cache data. Use the stream transport
1.70 + * service to asynchronously read this stream on a background thread.
1.71 + * The returned stream MAY implement nsISeekableStream.
1.72 + *
1.73 + * @param offset
1.74 + * read starting from this offset into the cached data. an offset
1.75 + * beyond the end of the stream has undefined consequences.
1.76 + *
1.77 + * @return non-blocking, buffered input stream.
1.78 + */
1.79 + nsIInputStream openInputStream(in long long offset);
1.80 +
1.81 + /**
1.82 + * Open non-blocking output stream to cache data. The returned stream
1.83 + * MAY implement nsISeekableStream.
1.84 + *
1.85 + * If opening an output stream to existing cached data, the data will be
1.86 + * truncated to the specified offset.
1.87 + *
1.88 + * @param offset
1.89 + * write starting from this offset into the cached data. an offset
1.90 + * beyond the end of the stream has undefined consequences.
1.91 + *
1.92 + * @return blocking, buffered output stream.
1.93 + */
1.94 + nsIOutputStream openOutputStream(in long long offset);
1.95 +
1.96 + /**
1.97 + * Stores the Content-Length specified in the HTTP header for this
1.98 + * entry. Checked before we write to the cache entry, to prevent ever
1.99 + * taking up space in the cache for an entry that we know up front
1.100 + * is going to have to be evicted anyway. See bug 588507.
1.101 + */
1.102 + attribute int64_t predictedDataSize;
1.103 +
1.104 + /**
1.105 + * Get/set security info on the cache entry for this descriptor.
1.106 + */
1.107 + attribute nsISupports securityInfo;
1.108 +
1.109 + /**
1.110 + * Get the size of the cache entry data, as stored. This may differ
1.111 + * from the entry's dataSize, if the entry is compressed.
1.112 + */
1.113 + readonly attribute unsigned long storageDataSize;
1.114 +
1.115 + /**
1.116 + * Asynchronously doom an entry. Listener will be notified about the status
1.117 + * of the operation. Null may be passed if caller doesn't care about the
1.118 + * result.
1.119 + */
1.120 + void asyncDoom(in nsICacheEntryDoomCallback listener);
1.121 +
1.122 + /**
1.123 + * Methods for accessing meta data. Meta data is a table of key/value
1.124 + * string pairs. The strings do not have to conform to any particular
1.125 + * charset, but they must be null terminated.
1.126 + */
1.127 + string getMetaDataElement(in string key);
1.128 + void setMetaDataElement(in string key, in string value);
1.129 +
1.130 + /**
1.131 + * Claims that all metadata on this entry are up-to-date and this entry
1.132 + * now can be delivered to other waiting consumers.
1.133 + *
1.134 + * We need such method since metadata must be delivered synchronously.
1.135 + */
1.136 + void metaDataReady();
1.137 +
1.138 + /**
1.139 + * Called by consumer upon 304/206 response from the server. This marks
1.140 + * the entry content as positively revalidated.
1.141 + * Consumer uses this method after the consumer has returned ENTRY_NEEDS_REVALIDATION
1.142 + * result from onCacheEntryCheck and after successfull revalidation with the server.
1.143 + */
1.144 + void setValid();
1.145 +
1.146 + /**
1.147 + * Doom this entry and open a new, empty, entry for write. Consumer has
1.148 + * to exchange the entry this method is called on for the newly created.
1.149 + * Used on 200 responses to conditional requests.
1.150 + *
1.151 + * @param aMemoryOnly
1.152 + * - whether the entry is to be created as memory/only regardless how
1.153 + * the entry being recreated persistence is set
1.154 + * @returns
1.155 + * - an entry that can be used to write to
1.156 + * @throws
1.157 + * - NS_ERROR_NOT_AVAILABLE when the entry cannot be from some reason
1.158 + * recreated for write
1.159 + */
1.160 + nsICacheEntry recreate([optional] in boolean aMemoryOnly);
1.161 +
1.162 + /**
1.163 + * Returns the length of data this entry holds.
1.164 + * @throws
1.165 + * NS_ERROR_IN_PROGRESS when the write is still in progress.
1.166 + */
1.167 + readonly attribute long long dataSize;
1.168 +
1.169 + /****************************************************************************
1.170 + * The following methods might be added to some nsICacheEntryInternal
1.171 + * interface since we want to remove them as soon as the old cache backend is
1.172 + * completely removed.
1.173 + */
1.174 +
1.175 + /**
1.176 + * @deprecated
1.177 + * FOR BACKWARD COMPATIBILITY ONLY
1.178 + * When the old cache backend is eventually removed, this method
1.179 + * can be removed too.
1.180 + *
1.181 + * In the new backend: this method is no-op
1.182 + * In the old backend: this method delegates to nsICacheEntryDescriptor.close()
1.183 + */
1.184 + void close();
1.185 +
1.186 + /**
1.187 + * @deprecated
1.188 + * FOR BACKWARD COMPATIBILITY ONLY
1.189 + * Marks the entry as valid so that others can use it and get only readonly
1.190 + * access when the entry is held by the 1st writer.
1.191 + */
1.192 + void markValid();
1.193 +
1.194 + /**
1.195 + * @deprecated
1.196 + * FOR BACKWARD COMPATIBILITY ONLY
1.197 + * Marks the entry as valid when write access is acquired.
1.198 + */
1.199 + void maybeMarkValid();
1.200 +
1.201 + /**
1.202 + * @deprecated
1.203 + * FOR BACKWARD COMPATIBILITY ONLY / KINDA HACK
1.204 + * @param aWriteAllowed
1.205 + * Consumer indicates whether write to the entry is allowed for it.
1.206 + * Depends on implementation how the flag is handled.
1.207 + * @returns
1.208 + * true when write access is acquired for this entry,
1.209 + * false otherwise
1.210 + */
1.211 + boolean hasWriteAccess(in boolean aWriteAllowed);
1.212 +};
