netwerk/cache/public/nsICacheSession.idlScriptable
Handles open synchronous and asynchronous cache entry operations along with evicting cache entries and checking for cache devices instantiation according to the session storage policies.
Inherits from: nsISupports Last changed in Gecko 14 (Firefox 14 / Thunderbird 14 / SeaMonkey 2.11)

Method overview

void asyncOpenCacheEntry(in ACString key, in nsCacheAccessMode accessRequested, in nsICacheListener listener, [optional] in boolean noWait);
void evictEntries();
PRBool isStorageEnabled();
nsICacheEntryDescriptor openCacheEntry(in ACString key, in nsCacheAccessMode accessRequested, in boolean blockingMode);
void doomEntry(in ACString key, in nsICacheListener listener);

Attributes

Attribute Type Description
doomEntriesIfExpired PRBool Expired entries will be doomed or evicted if this attribute is set to true. If false, expired entries will be returned (useful for offline mode and clients, such as HTTP, that can update the valid lifetime of cached content). This attribute defaults to true.

Methods

asyncOpenCacheEntry()

This method gives an asynchronous cache access. Does not block the calling thread. Instead, the listener will be notified when the descriptor is available.

void asyncOpenCacheEntry(
  in ACString key,
  in nsCacheAccessMode accessRequested,
  in nsICacheListener listener,
  [optional] in boolean noWait
);
Parameters
key
The key for cache entry.
accessRequested
The requested access.
listener
The cache listener to be notified.
noWait
Do not wait for the cache entry when it is in use and waits for validation.

doomEntry()

Asynchronously dooms an entry specified by the key.

void doomEntry(
  in ACString key,
  in nsICacheListener listener
);
Parameters
key
The key for cache entry.
listener
The cache listener to be notified (may be null).

evictEntries()

This method evicts all entries for this session's clientID according to its storagePolicy.

void evictEntries();
Parameters

None.

isStorageEnabled()

This method checks if the cache devices implied by the session storage policy are currently enabled for instantiation if they don't already exist.

PRBool isStorageEnabled();
Parameters

None.

Return value

Returns whether any of the cache devices implied by the session storage policy are currently enabled for instantiation or not, depending on their existence.

openCacheEntry()

This method gives a synchronous cache access. It returns a unique descriptor each time it is called, even if the same key is specified. When called by multiple threads for WRITE access, only one writable descriptor will be granted. If blockingMode is set to false, it will return NS_ERROR_CACHE_WAIT_FOR_VALIDATION rather than block when another descriptor has been given WRITE access but hasn't validated the entry yet.

Note: If at all possible, you should use asyncOpenCacheEntry() instead of calling openCacheEntry(), in order to avoid blocking on I/O on the calling thread. This will streamline overall application performance.

A cache session can only give out one descriptor with WRITE access to a given cache entry at a time. Until the client calls MarkValid on its descriptor, other attempts to open the same cache entry will block.

nsICacheEntryDescriptor openCacheEntry(
  in ACString key,
  in nsCacheAccessMode accessRequested,
  in boolean blockingMode
);
Parameters
key
The key for cache entry.
accessRequested
The requested access.
blockingMode
True or False value to turn blocking mode for calling the thread to ON/OFF respectively.
Return value

Returns a unique descriptor each time it is called.

See also