1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/cache/nsICache.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,142 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +typedef long nsCacheStoragePolicy;
1.13 +typedef long nsCacheAccessMode;
1.14 +
1.15 +/**
1.16 + * nsICache is a namespace for various cache constants. It does not represent
1.17 + * an actual object.
1.18 + */
1.19 +[scriptable, uuid(d6c67f38-b39a-4582-8a48-4c4f8a56dfd0)]
1.20 +interface nsICache
1.21 +{
1.22 + /**
1.23 + * Access Modes
1.24 + *
1.25 + *
1.26 + * Mode Requested | Not Cached | Cached
1.27 + * ------------------------------------------------------------------------
1.28 + * READ | KEY_NOT_FOUND | NS_OK
1.29 + * | Mode = NONE | Mode = READ
1.30 + * | No Descriptor | Descriptor
1.31 + * ------------------------------------------------------------------------
1.32 + * WRITE | NS_OK | NS_OK (Cache service
1.33 + * | Mode = WRITE | Mode = WRITE dooms existing
1.34 + * | Descriptor | Descriptor cache entry)
1.35 + * ------------------------------------------------------------------------
1.36 + * READ_WRITE | NS_OK | NS_OK
1.37 + * (1st req.) | Mode = WRITE | Mode = READ_WRITE
1.38 + * | Descriptor | Descriptor
1.39 + * ------------------------------------------------------------------------
1.40 + * READ_WRITE | N/A | NS_OK
1.41 + * (Nth req.) | | Mode = READ
1.42 + * | | Descriptor
1.43 + * ------------------------------------------------------------------------
1.44 + *
1.45 + *
1.46 + * Access Requested:
1.47 + *
1.48 + * READ - I only want to READ, if there isn't an entry just fail
1.49 + * WRITE - I have something new I want to write into the cache, make
1.50 + * me a new entry and doom the old one, if any.
1.51 + * READ_WRITE - I want to READ, but I'm willing to update an existing
1.52 + * entry if necessary, or create a new one if none exists.
1.53 + *
1.54 + *
1.55 + * Access Granted:
1.56 + *
1.57 + * NONE - No descriptor is provided. You get zilch. Nada. Nothing.
1.58 + * READ - You can READ from this descriptor.
1.59 + * WRITE - You must WRITE to this descriptor because the cache entry
1.60 + * was just created for you.
1.61 + * READ_WRITE - You can READ the descriptor to determine if it's valid,
1.62 + * you may WRITE if it needs updating.
1.63 + *
1.64 + *
1.65 + * Comments:
1.66 + *
1.67 + * If you think that you might need to modify cached data or meta data,
1.68 + * then you must open a cache entry requesting WRITE access. Only one
1.69 + * cache entry descriptor, per cache entry, will be granted WRITE access.
1.70 + *
1.71 + * Usually, you will request READ_WRITE access in order to first test the
1.72 + * meta data and informational fields to determine if a write (ie. going
1.73 + * to the net) may actually be necessary. If you determine that it is
1.74 + * not, then you would mark the cache entry as valid (using MarkValid) and
1.75 + * then simply read the data from the cache.
1.76 + *
1.77 + * A descriptor granted WRITE access has exclusive access to the cache
1.78 + * entry up to the point at which it marks it as valid. Once the cache
1.79 + * entry has been "validated", other descriptors with READ access may be
1.80 + * opened to the cache entry.
1.81 + *
1.82 + * If you make a request for READ_WRITE access to a cache entry, the cache
1.83 + * service will downgrade your access to READ if there is already a
1.84 + * cache entry descriptor open with WRITE access.
1.85 + *
1.86 + * If you make a request for only WRITE access to a cache entry and another
1.87 + * descriptor with WRITE access is currently open, then the existing cache
1.88 + * entry will be 'doomed', and you will be given a descriptor (with WRITE
1.89 + * access only) to a new cache entry.
1.90 + *
1.91 + */
1.92 + const nsCacheAccessMode ACCESS_NONE = 0;
1.93 + const nsCacheAccessMode ACCESS_READ = 1;
1.94 + const nsCacheAccessMode ACCESS_WRITE = 2;
1.95 + const nsCacheAccessMode ACCESS_READ_WRITE = 3;
1.96 +
1.97 + /**
1.98 + * Storage Policy
1.99 + *
1.100 + * The storage policy of a cache entry determines the device(s) to which
1.101 + * it belongs. See nsICacheSession and nsICacheEntryDescriptor for more
1.102 + * details.
1.103 + *
1.104 + * STORE_ANYWHERE - Allows the cache entry to be stored in any device.
1.105 + * The cache service decides which cache device to use
1.106 + * based on "some resource management calculation."
1.107 + * STORE_IN_MEMORY - Requires the cache entry to reside in non-persistent
1.108 + * storage (ie. typically in system RAM).
1.109 + * STORE_ON_DISK - Requires the cache entry to reside in persistent
1.110 + * storage (ie. typically on a system's hard disk).
1.111 + * STORE_OFFLINE - Requires the cache entry to reside in persistent,
1.112 + * reliable storage for offline use.
1.113 + */
1.114 + const nsCacheStoragePolicy STORE_ANYWHERE = 0;
1.115 + const nsCacheStoragePolicy STORE_IN_MEMORY = 1;
1.116 + const nsCacheStoragePolicy STORE_ON_DISK = 2;
1.117 + // value 3 was used by STORE_ON_DISK_AS_FILE which was removed
1.118 + const nsCacheStoragePolicy STORE_OFFLINE = 4;
1.119 +
1.120 + /**
1.121 + * All entries for a cache session are stored as streams of data or
1.122 + * as objects. These constant my be used to specify the type of entries
1.123 + * when calling nsICacheService::CreateSession().
1.124 + */
1.125 + const long NOT_STREAM_BASED = 0;
1.126 + const long STREAM_BASED = 1;
1.127 +
1.128 + /**
1.129 + * The synchronous OpenCacheEntry() may be blocking or non-blocking. If a cache entry is
1.130 + * waiting to be validated by another cache descriptor (so no new cache descriptors for that
1.131 + * key can be created, OpenCacheEntry() will return NS_ERROR_CACHE_WAIT_FOR_VALIDATION in
1.132 + * non-blocking mode. In blocking mode, it will wait until the cache entry for the key has
1.133 + * been validated or doomed. If the cache entry is validated, then a descriptor for that
1.134 + * entry will be created and returned. If the cache entry was doomed, then a descriptor
1.135 + * will be created for a new cache entry for the key.
1.136 + */
1.137 + const long NON_BLOCKING = 0;
1.138 + const long BLOCKING = 1;
1.139 +
1.140 + /**
1.141 + * Constant meaning no expiration time.
1.142 + */
1.143 + const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;
1.144 +};
1.145 +
