From 8706317ae27a9deefdd6ea0a8947b8f6dffac082 Mon Sep 17 00:00:00 2001 From: "gordon%netscape.com" Date: Fri, 23 Feb 2001 23:20:15 +0000 Subject: [PATCH] Add nsICache.idl for common typedefs and constants. These changes are not part of the build. r = beard, darin. --- netwerk/cache/public/nsICache.idl | 120 ++++++++++++++++++ .../cache/public/nsICacheEntryDescriptor.idl | 57 +++------ netwerk/cache/public/nsICacheListener.idl | 8 +- netwerk/cache/public/nsICacheService.idl | 55 ++------ netwerk/cache/public/nsICacheSession.idl | 28 ++-- netwerk/cache/public/nsICacheVisitor.idl | 7 +- 6 files changed, 172 insertions(+), 103 deletions(-) create mode 100644 netwerk/cache/public/nsICache.idl diff --git a/netwerk/cache/public/nsICache.idl b/netwerk/cache/public/nsICache.idl new file mode 100644 index 000000000000..7365a82ac28b --- /dev/null +++ b/netwerk/cache/public/nsICache.idl @@ -0,0 +1,120 @@ +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- + * + * The contents of this file are subject to the Mozilla Public + * License Version 1.1 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an "AS + * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or + * implied. See the License for the specific language governing + * rights and limitations under the License. + * + * The Original Code is nsICache.idl, released February 23, 2001. + * + * The Initial Developer of the Original Code is Netscape Communications + * Corporation. Portions created by Netscape are + * Copyright (C) 2001 Netscape Communications Corporation. All + * Rights Reserved. + * + * Contributor(s): + * Gordon Sheridan + * Patrick Beard + * Darin Fisher + */ + + + +typedef long nsCacheStoragePolicy; +typedef long nsCacheAccessMode; + +[scriptable, uuid(ec1c0063-197d-44bb-84ba-7525d50fc937)] +interface nsICache +{ + /** + * Cache Access Mode + * + * + * Mode Requested | Not Cached | Cached + * -------------------------------------------------------------------------- + * READ | NS_NOT_IN_CACHE | NS_OK + * | Flags = 0 | Flags = READ + * | No Channel | Channel + * -------------------------------------------------------------------------- + * WRITE | NS_OK | NS_OK (Cache manager + * | Flags = WRITE | Flags = WRITE dooms existing + * | Channel | Channel cache object) + * -------------------------------------------------------------------------- + * READ|WRITE | NS_OK | NS_OK + * (1st req.) | Flags = WRITE | Flags = READ|WRITE + * | Channel | Channel + * -------------------------------------------------------------------------- + * READ|WRITE | N/A | NS_OK + * (Nth req.) | | Flags = READ + * | | Channel + * -------------------------------------------------------------------------- + * + * + * If you think that you might need to modify cached data or meta data, then + * you must open a cache entry with the WRITE flag set. Only one cache + * entry descriptor, per cache entry, will be granted WRITE permission. + * + * Usually, you will set both the READ and WRITE flags in order to first test + * the meta data and informational fields to determine if a write (ie. going + * to the net) may actually be necessary. If you determine that it is not, + * then you would mark the cache entry as valid (using MarkValid) and then + * simply read the data from the cache. + * + * A descriptor granted WRITE access has exclusive access to the cache entry + * up until the point at which it marks it as valid. Once the + * cache entry has been "validated", other descriptors with READ access may be + * opened to the cache entry. + * + * If you make a request for READ|WRITE access to a cache entry, the cache + * service will downgrade your access to READ if there is already a + * cache entry descriptor open with WRITE access. + * + * If you make a request for WRITE access to a cache entry (without the READ + * flag set) and another descriptor with WRITE access is currently + * open, then the existing cache entry will be 'doomed', and you will be given + * a descriptor (with WRITE access only) to a new cache entry. + * + * Access Requested: + * READ - I only want to READ, if there isn't an entry just fail + * WRITE - I have something new I want to write into the cache, make me a new + * entry and doom the old one, if any. + * READ_WRITE - I want to READ, but I'm willing to update an existing entry if + * necessary, or create a new one if none exists. + * + * Access Granted: + * NO_ACCESS - No descriptor is provided. You get zilch. Nada. Nothing. + * READ - You can READ from this descriptor + * WRITE - You must WRITE to this descriptor because the cache entry was just + * created for you + * READ_WRITE - You can READ the descriptor to determine if it's valid, + * you may WRITE if it needs updating + */ + const nsCacheAccessMode ACCESS_NONE = 0; + const nsCacheAccessMode ACCESS_READ = 1; + const nsCacheAccessMode ACCESS_WRITE = 2; + const nsCacheAccessMode ACCESS_READ_WRITE = 3; + + /** + * Storage Policy + */ + const nsCacheStoragePolicy STORE_ANYWHERE = 0; + const nsCacheStoragePolicy STORE_IN_MEMORY = 1; + const nsCacheStoragePolicy STORE_ON_DISK = 2; +}; + + + +%{C++ + +#define NS_ERROR_CACHE_KEY_NOT_FOUND NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 60) +#define NS_ERROR_CACHE_DATA_IS_STREAM NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 61) +#define NS_ERROR_CACHE_DATA_IS_NOT_STREAM NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 62) +#define NS_ERROR_CACHE_WAIT_FOR_VALIDATION NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 63) +#define NS_ERROR_CACHE_ENTRY_DOOMED NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 64) + +%} diff --git a/netwerk/cache/public/nsICacheEntryDescriptor.idl b/netwerk/cache/public/nsICacheEntryDescriptor.idl index 593df638dd90..e8941faa5771 100644 --- a/netwerk/cache/public/nsICacheEntryDescriptor.idl +++ b/netwerk/cache/public/nsICacheEntryDescriptor.idl @@ -19,10 +19,13 @@ * Rights Reserved. * * Contributor(s): - * Gordon Sheridan, 10-February-2001 + * Gordon Sheridan + * Patrick Beard + * Darin Fisher */ #include "nsITransport.idl" +#include "nsICache.idl" interface nsISimpleEnumerator; interface nsICacheListener; @@ -35,42 +38,32 @@ interface nsICacheEntryDescriptor : nsITransport * attributes from cache entry */ - readonly attribute string clientID; - readonly attribute string key; - readonly attribute PRTime lastValidated; - readonly attribute PRTime lastFetch; - readonly attribute unsigned long fetchCount; + readonly attribute string key; + readonly attribute long fetchCount; + readonly attribute PRTime lastFetched; + readonly attribute PRTime lastValidated; - attribute PRTime expiresDate; - attribute boolean streamBased; + attribute PRTime expirationTime; + + /** + * Indicate whether the cached data is a stream or object. + */ + boolean isStreamBased(); /** * For accessing non-persistent cached objects */ - attribute nsISupports cacheElement; - - + attribute nsISupports cacheElement; + /** * Access granted to this descriptor. (see nsICacheService.idl) */ readonly attribute unsigned long accessGranted; /** - * Storage flags + * */ - - const unsigned long DONT_CACHE = 0; - const unsigned long ALLOW_IN_MEMORY = 1; - const unsigned long ALLOW_ON_DISK = 2; - const unsigned long ALLOW_IN_MEMORY_OR_ON_DISK = 3; - - attribute unsigned long storageFlags; - - /* and/or */ - - attribute boolean allowInMemory; - attribute boolean allowOnDisk; - + attribute nsCacheStoragePolicy storagePolicy; /** * Doom the cache entry this descriptor references in order to slate it for @@ -79,19 +72,6 @@ interface nsICacheEntryDescriptor : nsITransport void doom(); void doomAndFailPendingRequests(in nsresult status); - /** - * Data in an existing cache object may only be appended to. Therefore, - * a writer wishing to replace existing cache data should first truncate - * the existing data to the appropriate length. - */ - void truncateExistingData(in unsigned long newLength); - - /** - * Set internal flag so we know more data is expected than what is there currently. - * - */ - void appendToExistingData(); - /** * A writer must validate this cache object before any readers are given * a descriptor to the object. @@ -105,6 +85,5 @@ interface nsICacheEntryDescriptor : nsITransport void setMetadataElement(in string key, in string value); nsISimpleEnumerator getMetaDataEnumerator(); - }; diff --git a/netwerk/cache/public/nsICacheListener.idl b/netwerk/cache/public/nsICacheListener.idl index a13f214fef7c..f2a8879a94f6 100644 --- a/netwerk/cache/public/nsICacheListener.idl +++ b/netwerk/cache/public/nsICacheListener.idl @@ -18,11 +18,15 @@ * Rights Reserved. * * Contributor(s): - * Gordon Sheridan, 19-January-2001 + * Gordon Sheridan + * Patrick Beard + * Darin Fisher */ #include "nsISupports.idl" +#include "nsICache.idl" + interface nsICacheEntryDescriptor; @@ -35,6 +39,6 @@ interface nsICacheListener : nsISupports * See nsICacheService.idl for accessGranted values. */ void onDescriptorAvailable(in nsICacheEntryDescriptor descriptor, - in unsigned long accessGranted, + in nsCacheAccessMode accessGranted, in nsresult status); }; diff --git a/netwerk/cache/public/nsICacheService.idl b/netwerk/cache/public/nsICacheService.idl index f214601ef061..7a64ff8ea516 100644 --- a/netwerk/cache/public/nsICacheService.idl +++ b/netwerk/cache/public/nsICacheService.idl @@ -18,71 +18,36 @@ * Rights Reserved. * * Contributor(s): - * Gordon Sheridan, 10-February-2001 + * Gordon Sheridan + * Patrick Beard + * Darin Fisher */ #include "nsISupports.idl" -#include "nsICacheEntryDescriptor.idl" interface nsISimpleEnumerator; interface nsICacheListener; +interface nsICacheSession; +interface nsICacheVisitor; [scriptable, uuid(0ebec4c7-742f-4f27-8e7b-7c8a0cc76348)] interface nsICacheService : nsISupports { - void init(); void shutdown(); - /** - * Access flags. - */ - const unsigned long NO_ACCESS = 0; - const unsigned long READ = 1; - const unsigned long WRITE = 2; - const unsigned long READ_WRITE = 3; - /* - * Synchronous cache access. This 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 writeable - * descriptor will be granted. + * Create Session */ - nsICacheEntryDescriptor openCacheEntry(in string clientID, - in string key, - in unsigned long accessFlagsRequested, - in boolean streamBased); - - - /* - * Asynchronous cache access. Does not block the calling thread. - */ - void asyncOpenCacheEntry(in string clientID, - in string key, - in unsigned long accessFlagsRequested, - in boolean streamBased, - in nsICacheListener listener); - + nsICacheSession createSession(in string clientID, + in long storagePolicy, + in boolean streamBased); /* * methods for implementing about:cache */ - nsISimpleEnumerator enumerateDeviceIDs(); - nsISimpleEnumerator enumerateClientIDs(); - nsISimpleEnumerator enumerateEntries(in string deviceID, - in string clientID); - + void visitEntries(in nsICacheVisitor visitor); }; - -%{C++ - -#define NS_ERROR_CACHE_KEY_NOT_FOUND NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 60) -#define NS_ERROR_CACHE_DATA_IS_STREAM NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 61) -#define NS_ERROR_CACHE_DATA_IS_NOT_STREAM NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 62) -#define NS_ERROR_CACHE_WAIT_FOR_VALIDATION NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 63) -#define NS_ERROR_CACHE_ENTRY_DOOMED NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 64) - -%} diff --git a/netwerk/cache/public/nsICacheSession.idl b/netwerk/cache/public/nsICacheSession.idl index caa4803f6f79..f992b445a1be 100644 --- a/netwerk/cache/public/nsICacheSession.idl +++ b/netwerk/cache/public/nsICacheSession.idl @@ -10,7 +10,7 @@ * implied. See the License for the specific language governing * rights and limitations under the License. * - * The Original Code is nsICacheService.idl, released February 23, 2001. + * The Original Code is nsICacheSession.idl, released February 23, 2001. * * The Initial Developer of the Original Code is Netscape Communications * Corporation. Portions created by Netscape are @@ -18,36 +18,36 @@ * Rights Reserved. * * Contributor(s): - * Gordon Sheridan, 23-February-2001 + * Gordon Sheridan + * Patrick Beard + * Darin Fisher */ #include "nsISupports.idl" -#include "nsICacheEntryDescriptor.idl" +#include "nsICache.idl" + +interface nsICacheEntryDescriptor; +interface nsICacheListener; + [scriptable, uuid(b4b419ad-28b7-4d25-9988-20fa98505a19)] interface nsICacheSession : nsISupports { - - /* * Synchronous cache access. This 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 writeable * descriptor will be granted. */ - nsICacheEntryDescriptor openCacheEntry(in string key, - in unsigned long accessFlagsRequested); + nsICacheEntryDescriptor openCacheEntry(in string key, + in nsCacheAccessMode accessRequested); /* * Asynchronous cache access. Does not block the calling thread. */ - void asyncOpenCacheEntry(in string clientID, - in string key, - in unsigned long accessFlagsRequested, - in boolean streamBased, - in nsICacheListener listener); - - + void asyncOpenCacheEntry(in string key, + in nsCacheAccessMode accessRequested, + in nsICacheListener listener); }; diff --git a/netwerk/cache/public/nsICacheVisitor.idl b/netwerk/cache/public/nsICacheVisitor.idl index 3bf9a5f2d7d2..b27263f4d371 100644 --- a/netwerk/cache/public/nsICacheVisitor.idl +++ b/netwerk/cache/public/nsICacheVisitor.idl @@ -10,7 +10,7 @@ * implied. See the License for the specific language governing * rights and limitations under the License. * - * The Original Code is nsICacheService.idl, released February 23, 2001. + * The Original Code is nsICacheVisitor.idl, released February 23, 2001. * * The Initial Developer of the Original Code is Netscape Communications * Corporation. Portions created by Netscape are @@ -18,7 +18,9 @@ * Rights Reserved. * * Contributor(s): - * Gordon Sheridan, 23-February-2001 + * Gordon Sheridan + * Patrick Beard + * Darin Fisher */ @@ -33,7 +35,6 @@ interface nsICacheVisitor : nsISupports boolean visitDevice(in string deviceID, in nsISupports deviceInfo); /* XXX we should define device info as well (stats, etc)*/ - /** * return true to visit the next entry on current device */