nsICacheEntryDescriptor Interface

[scriptable, uuid(49c1a11d-f5d2-4f09-8262-551e64908ada)]

Attributes

 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 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

 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/set the storage policy of the cache entry.  See nsICache.idl for
 the definitions of the storage policies.

attribute nsCacheStoragePolicy storagePolicy

Methods

  Explicitly close the descriptor (optional).

void close()

 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)

 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)

 A writer must validate this cache object before any readers are given
 a descriptor to the object.

void markValid()

 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)

 Set the cache entry data size.  This will fail if the cache entry
 IS stream based.

void setDataSize(in unsigned long size)

 Set the time at which the cache entry should be considered invalid (in
 seconds since the Epoch).

void setExpirationTime(in PRUint32 expirationTime)

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)