michael@0: /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- michael@0: * michael@0: * This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: typedef long nsCacheStoragePolicy; michael@0: typedef long nsCacheAccessMode; michael@0: michael@0: /** michael@0: * nsICache is a namespace for various cache constants. It does not represent michael@0: * an actual object. michael@0: */ michael@0: [scriptable, uuid(d6c67f38-b39a-4582-8a48-4c4f8a56dfd0)] michael@0: interface nsICache michael@0: { michael@0: /** michael@0: * Access Modes michael@0: * michael@0: * michael@0: * Mode Requested | Not Cached | Cached michael@0: * ------------------------------------------------------------------------ michael@0: * READ | KEY_NOT_FOUND | NS_OK michael@0: * | Mode = NONE | Mode = READ michael@0: * | No Descriptor | Descriptor michael@0: * ------------------------------------------------------------------------ michael@0: * WRITE | NS_OK | NS_OK (Cache service michael@0: * | Mode = WRITE | Mode = WRITE dooms existing michael@0: * | Descriptor | Descriptor cache entry) michael@0: * ------------------------------------------------------------------------ michael@0: * READ_WRITE | NS_OK | NS_OK michael@0: * (1st req.) | Mode = WRITE | Mode = READ_WRITE michael@0: * | Descriptor | Descriptor michael@0: * ------------------------------------------------------------------------ michael@0: * READ_WRITE | N/A | NS_OK michael@0: * (Nth req.) | | Mode = READ michael@0: * | | Descriptor michael@0: * ------------------------------------------------------------------------ michael@0: * michael@0: * michael@0: * Access Requested: michael@0: * michael@0: * READ - I only want to READ, if there isn't an entry just fail michael@0: * WRITE - I have something new I want to write into the cache, make michael@0: * me a new entry and doom the old one, if any. michael@0: * READ_WRITE - I want to READ, but I'm willing to update an existing michael@0: * entry if necessary, or create a new one if none exists. michael@0: * michael@0: * michael@0: * Access Granted: michael@0: * michael@0: * NONE - No descriptor is provided. You get zilch. Nada. Nothing. michael@0: * READ - You can READ from this descriptor. michael@0: * WRITE - You must WRITE to this descriptor because the cache entry michael@0: * was just created for you. michael@0: * READ_WRITE - You can READ the descriptor to determine if it's valid, michael@0: * you may WRITE if it needs updating. michael@0: * michael@0: * michael@0: * Comments: michael@0: * michael@0: * If you think that you might need to modify cached data or meta data, michael@0: * then you must open a cache entry requesting WRITE access. Only one michael@0: * cache entry descriptor, per cache entry, will be granted WRITE access. michael@0: * michael@0: * Usually, you will request READ_WRITE access in order to first test the michael@0: * meta data and informational fields to determine if a write (ie. going michael@0: * to the net) may actually be necessary. If you determine that it is michael@0: * not, then you would mark the cache entry as valid (using MarkValid) and michael@0: * then simply read the data from the cache. michael@0: * michael@0: * A descriptor granted WRITE access has exclusive access to the cache michael@0: * entry up to the point at which it marks it as valid. Once the cache michael@0: * entry has been "validated", other descriptors with READ access may be michael@0: * opened to the cache entry. michael@0: * michael@0: * If you make a request for READ_WRITE access to a cache entry, the cache michael@0: * service will downgrade your access to READ if there is already a michael@0: * cache entry descriptor open with WRITE access. michael@0: * michael@0: * If you make a request for only WRITE access to a cache entry and another michael@0: * descriptor with WRITE access is currently open, then the existing cache michael@0: * entry will be 'doomed', and you will be given a descriptor (with WRITE michael@0: * access only) to a new cache entry. michael@0: * michael@0: */ michael@0: const nsCacheAccessMode ACCESS_NONE = 0; michael@0: const nsCacheAccessMode ACCESS_READ = 1; michael@0: const nsCacheAccessMode ACCESS_WRITE = 2; michael@0: const nsCacheAccessMode ACCESS_READ_WRITE = 3; michael@0: michael@0: /** michael@0: * Storage Policy michael@0: * michael@0: * The storage policy of a cache entry determines the device(s) to which michael@0: * it belongs. See nsICacheSession and nsICacheEntryDescriptor for more michael@0: * details. michael@0: * michael@0: * STORE_ANYWHERE - Allows the cache entry to be stored in any device. michael@0: * The cache service decides which cache device to use michael@0: * based on "some resource management calculation." michael@0: * STORE_IN_MEMORY - Requires the cache entry to reside in non-persistent michael@0: * storage (ie. typically in system RAM). michael@0: * STORE_ON_DISK - Requires the cache entry to reside in persistent michael@0: * storage (ie. typically on a system's hard disk). michael@0: * STORE_OFFLINE - Requires the cache entry to reside in persistent, michael@0: * reliable storage for offline use. michael@0: */ michael@0: const nsCacheStoragePolicy STORE_ANYWHERE = 0; michael@0: const nsCacheStoragePolicy STORE_IN_MEMORY = 1; michael@0: const nsCacheStoragePolicy STORE_ON_DISK = 2; michael@0: // value 3 was used by STORE_ON_DISK_AS_FILE which was removed michael@0: const nsCacheStoragePolicy STORE_OFFLINE = 4; michael@0: michael@0: /** michael@0: * All entries for a cache session are stored as streams of data or michael@0: * as objects. These constant my be used to specify the type of entries michael@0: * when calling nsICacheService::CreateSession(). michael@0: */ michael@0: const long NOT_STREAM_BASED = 0; michael@0: const long STREAM_BASED = 1; michael@0: michael@0: /** michael@0: * The synchronous OpenCacheEntry() may be blocking or non-blocking. If a cache entry is michael@0: * waiting to be validated by another cache descriptor (so no new cache descriptors for that michael@0: * key can be created, OpenCacheEntry() will return NS_ERROR_CACHE_WAIT_FOR_VALIDATION in michael@0: * non-blocking mode. In blocking mode, it will wait until the cache entry for the key has michael@0: * been validated or doomed. If the cache entry is validated, then a descriptor for that michael@0: * entry will be created and returned. If the cache entry was doomed, then a descriptor michael@0: * will be created for a new cache entry for the key. michael@0: */ michael@0: const long NON_BLOCKING = 0; michael@0: const long BLOCKING = 1; michael@0: michael@0: /** michael@0: * Constant meaning no expiration time. michael@0: */ michael@0: const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF; michael@0: }; michael@0: