summaryrefslogtreecommitdiffstats
path: root/netwerk/cache/nsICacheEntryDescriptor.idl
diff options
context:
space:
mode:
Diffstat (limited to 'netwerk/cache/nsICacheEntryDescriptor.idl')
-rw-r--r--netwerk/cache/nsICacheEntryDescriptor.idl164
1 files changed, 164 insertions, 0 deletions
diff --git a/netwerk/cache/nsICacheEntryDescriptor.idl b/netwerk/cache/nsICacheEntryDescriptor.idl
new file mode 100644
index 000000000..20fac747d
--- /dev/null
+++ b/netwerk/cache/nsICacheEntryDescriptor.idl
@@ -0,0 +1,164 @@
+/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsICacheVisitor.idl"
+#include "nsICache.idl"
+
+interface nsISimpleEnumerator;
+interface nsICacheListener;
+interface nsIInputStream;
+interface nsIOutputStream;
+interface nsIFile;
+interface nsICacheMetaDataVisitor;
+
+
+[scriptable, uuid(90b17d31-46aa-4fb1-a206-473c966cbc18)]
+interface nsICacheEntryDescriptor : nsICacheEntryInfo
+{
+ /**
+ * Set the time at which the cache entry should be considered invalid (in
+ * seconds since the Epoch).
+ */
+ void setExpirationTime(in uint32_t expirationTime);
+
+ /**
+ * Set the cache entry data size. This will fail if the cache entry
+ * IS stream based.
+ */
+ void setDataSize(in unsigned long size);
+
+ /**
+ * Open blocking input stream to cache data. This will fail if the cache
+ * entry IS NOT stream based. Use the stream transport service to
+ * asynchronously read this stream on a background thread. The returned
+ * stream MAY implement nsISeekableStream.
+ *
+ * @param offset
+ * read starting from this offset into the cached data. an offset
+ * beyond the end of the stream has undefined consequences.
+ *
+ * @return blocking, unbuffered input stream.
+ */
+ nsIInputStream openInputStream(in unsigned long offset);
+
+ /**
+ * Open blocking output stream to cache data. This will fail if the cache
+ * entry IS NOT stream based. Use the stream transport service to
+ * asynchronously write to this stream on a background thread. The returned
+ * stream MAY implement nsISeekableStream.
+ *
+ * If opening an output stream to existing cached data, the data will be
+ * truncated to the specified offset.
+ *
+ * @param offset
+ * write starting from this offset into the cached data. an offset
+ * beyond the end of the stream has undefined consequences.
+ *
+ * @return blocking, unbuffered output stream.
+ */
+ nsIOutputStream openOutputStream(in unsigned long offset);
+
+ /**
+ * Get/set the cache data element. This will fail if the cache entry
+ * IS stream based. The cache entry holds a strong reference to this
+ * object. The object will be released when the cache entry is destroyed.
+ */
+ attribute nsISupports cacheElement;
+
+ /**
+ * Stores the Content-Length specified in the HTTP header for this
+ * entry. Checked before we write to the cache entry, to prevent ever
+ * taking up space in the cache for an entry that we know up front
+ * is going to have to be evicted anyway. See bug 588507.
+ */
+ attribute int64_t predictedDataSize;
+
+ /**
+ * Get the access granted to this descriptor. See nsICache.idl for the
+ * definitions of the access modes and a thorough description of their
+ * corresponding meanings.
+ */
+ readonly attribute nsCacheAccessMode accessGranted;
+
+ /**
+ * Get/set the storage policy of the cache entry. See nsICache.idl for
+ * the definitions of the storage policies.
+ */
+ attribute nsCacheStoragePolicy storagePolicy;
+
+ /**
+ * Get the disk file associated with the cache entry.
+ */
+ readonly attribute nsIFile file;
+
+ /**
+ * Get/set security info on the cache entry for this descriptor. This fails
+ * if the storage policy is not STORE_IN_MEMORY.
+ */
+ attribute nsISupports securityInfo;
+
+ /**
+ * Get the size of the cache entry data, as stored. This may differ
+ * from the entry's dataSize, if the entry is compressed.
+ */
+ readonly attribute unsigned long storageDataSize;
+
+ /**
+ * Doom the cache entry this descriptor references in order to slate it for
+ * removal. Once doomed a cache entry cannot be undoomed.
+ *
+ * A descriptor with WRITE access can doom the cache entry and choose to
+ * fail pending requests. This means that pending requests will not get
+ * a cache descriptor. This is meant as a tool for clients that wish to
+ * instruct pending requests to skip the cache.
+ */
+ void doom();
+ void doomAndFailPendingRequests(in nsresult status);
+
+ /**
+ * Asynchronously doom an entry. Listener will be notified about the status
+ * of the operation. Null may be passed if caller doesn't care about the
+ * result.
+ */
+ void asyncDoom(in nsICacheListener listener);
+
+ /**
+ * A writer must validate this cache object before any readers are given
+ * a descriptor to the object.
+ */
+ void markValid();
+
+ /**
+ * Explicitly close the descriptor (optional).
+ */
+
+ void close();
+
+ /**
+ * Methods for accessing meta data. Meta data is a table of key/value
+ * string pairs. The strings do not have to conform to any particular
+ * charset, but they must be null terminated.
+ */
+ string getMetaDataElement(in string key);
+ void setMetaDataElement(in string key, in string value);
+
+ /**
+ * Visitor will be called with key/value pair for each meta data element.
+ */
+ void visitMetaData(in nsICacheMetaDataVisitor visitor);
+};
+
+
+
+[scriptable, uuid(22f9a49c-3cf8-4c23-8006-54efb11ac562)]
+interface nsICacheMetaDataVisitor : nsISupports
+{
+ /**
+ * Called for each key/value pair in the meta data for a cache entry
+ */
+ boolean visitMetaDataElement(in string key,
+ in string value);
+};