gecko/netwerk/cache/nsICacheEntryDescriptor.idl
2012-05-21 12:12:37 +01:00

158 lines
5.3 KiB
Plaintext

/* -*- 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(49c1a11d-f5d2-4f09-8262-551e64908ada)]
interface nsICacheEntryDescriptor : nsICacheEntryInfo
{
/**
* Set the time at which the cache entry should be considered invalid (in
* seconds since the Epoch).
*/
void setExpirationTime(in PRUint32 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 PRInt64 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);
/**
* 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);
};