netwerk/cache/nsICacheEntryDescriptor.idlScriptable
This interface provides a cache entry descriptor.
Inherits from: nsICacheEntryInfo Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Method overview

void close();
void doom();
void doomAndFailPendingRequests(in nsresult status);
string getMetaDataElement(in string key);
void markValid();
nsIInputStream openInputStream(in unsigned long offset);
nsIOutputStream openOutputStream(in unsigned long offset);
void setDataSize(in unsigned long size);
void setExpirationTime(in PRUint32 expirationTime);
void setMetaDataElement(in string key, in string value);
void visitMetaData(in nsICacheMetaDataVisitor visitor);

Attributes

Attribute Type Description
accessGranted nsCacheAccessMode Get the access granted to this descriptor. See nsICache for the definitions of the access modes and a thorough description of their corresponding meanings. Read only.
cacheElement nsISupports Get or 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.
file nsIFile Get the disk file associated with the cache entry. Read only.
predictedDataSize PRInt64 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.
securityInfo nsISupports Get or set security info on the cache entry for this descriptor. This fails if the storage policy is not STORE_IN_MEMORY.
storagePolicy nsCacheStoragePolicy Get or set the storage policy of the cache entry. See nsICache for the definitions of the storage policies.

Methods

close()

This method explicitly closes the descriptor (optional).

void close();
Parameters

None.

doom()

This method dooms 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();
Parameters

None.

doomAndFailPendingRequests()

This method with the 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 doomAndFailPendingRequests(
  in nsresult status
);
Parameters
status
The access status.

getMetaDataElement()

This method retrieves the 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
);
Parameters
key
The key for retrieving the meta data.
Return value

Returns the string value containing the meta data for the provided key.

markValid()

This method means that a writer must validate this cache object before any readers are given a descriptor to the object.

void markValid();
Parameters

None.

openInputStream()

This method opens 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.

nsIInputStream openInputStream(
  in unsigned long offset
);
Parameters
offset
Read starting from this offset into the cached data. An offset beyond the end of the stream has undefined consequences.
Return value

Returns blocking, unbuffered input stream.

openOutputStream()

This method opens 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.

nsIOutputStream openOutputStream(
  in unsigned long offset
);
Parameters
offset
Write starting from this offset into the cached data. An offset beyond the end of the stream has undefined consequences.
Return value

Returns blocking, unbuffered output stream.

setDataSize()

This method sets the cache entry data size. This will fail if the cache entry is stream based.

void setDataSize(
  in unsigned long size
);
Parameters
size
The cache entry data size.

setExpirationTime()

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

void setExpirationTime(
  in PRUint32 expirationTime
);
Parameters
expirationTime
The time for cache entry expiration (in seconds).

setMetaDataElement()

This method sets the 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.

void setMetaDataElement(
  in string key,
  in string value
);
Parameters
key
The key for setting the meta data.
value
The value for setting the meta data.

visitMetaData()

This method means that the visitor will be called with key/value pair for each meta data element.

void visitMetaData(
  in nsICacheMetaDataVisitor visitor
);
Parameters
visitor
The visitor to be called.

See also