netwerk/cache/public/nsICache.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is nsICache.idl, released
  17  * February 23, 2001.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 2001
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *   Gordon Sheridan <gordon@netscape.com>
  26  *   Patrick Beard <beard@netscape.com>
  27  *   Darin Fisher <darin@netscape.com>
  28  *
  29  * Alternatively, the contents of this file may be used under the terms of
  30  * either the GNU General Public License Version 2 or later (the "GPL"), or
  31  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  32  * in which case the provisions of the GPL or the LGPL are applicable instead
  33  * of those above. If you wish to allow use of your version of this file only
  34  * under the terms of either the GPL or the LGPL, and not to allow others to
  35  * use your version of this file under the terms of the MPL, indicate your
  36  * decision by deleting the provisions above and replace them with the notice
  37  * and other provisions required by the GPL or the LGPL. If you do not delete
  38  * the provisions above, a recipient may use your version of this file under
  39  * the terms of any one of the MPL, the GPL or the LGPL.
  40  *
  41  * ***** END LICENSE BLOCK ***** */
  42
  43 #include "nsISupports.idl"
  44
  45 typedef long nsCacheStoragePolicy;
  46 typedef long nsCacheAccessMode;
  47
  48 /**
  49  * nsICache is a namespace for various cache constants.  It does not represent
  50  * an actual object.
  51  */
  52 [scriptable, uuid(ec1c0063-197d-44bb-84ba-7525d50fc937)]
  53 interface nsICache
  54 {
  55     /**
  56      * Access Modes
  57      *
  58      *
  59      * Mode Requested | Not Cached          | Cached
  60      * ------------------------------------------------------------------------
  61      * READ           | KEY_NOT_FOUND       | NS_OK
  62      *                | Mode = NONE         | Mode = READ
  63      *                | No Descriptor       | Descriptor
  64      * ------------------------------------------------------------------------
  65      * WRITE          | NS_OK               | NS_OK            (Cache service
  66      *                | Mode = WRITE        | Mode = WRITE      dooms existing
  67      *                | Descriptor          | Descriptor        cache entry)
  68      * ------------------------------------------------------------------------
  69      * READ_WRITE     | NS_OK               | NS_OK
  70      * (1st req.)     | Mode = WRITE        | Mode = READ_WRITE
  71      *                | Descriptor          | Descriptor
  72      * ------------------------------------------------------------------------
  73      * READ_WRITE     | N/A                 | NS_OK
  74      * (Nth req.)     |                     | Mode = READ
  75      *                |                     | Descriptor
  76      * ------------------------------------------------------------------------
  77      *
  78      *
  79      * Access Requested:
  80      *
  81      * READ            - I only want to READ, if there isn't an entry just fail
  82      * WRITE       - I have something new I want to write into the cache, make
  83      *               me a new entry and doom the old one, if any.
  84      * READ_WRITE  - I want to READ, but I'm willing to update an existing
  85      *               entry if necessary, or create a new one if none exists.
  86      *
  87      *
  88      * Access Granted:
  89      *
  90      * NONE        - No descriptor is provided. You get zilch. Nada. Nothing.
  91      * READ                - You can READ from this descriptor.
  92      * WRITE       - You must WRITE to this descriptor because the cache entry
  93      *               was just created for you.
  94      * READ_WRITE  - You can READ the descriptor to determine if it's valid,
  95      *               you may WRITE if it needs updating.
  96      *
  97      *
  98      * Comments:
  99      *
 100      * If you think that you might need to modify cached data or meta data,
 101      * then you must open a cache entry requesting WRITE access.  Only one
 102      * cache entry descriptor, per cache entry, will be granted WRITE access.
 103      *
 104      * Usually, you will request READ_WRITE access in order to first test the
 105      * meta data and informational fields to determine if a write (ie. going
 106      * to the net) may actually be necessary.  If you determine that it is
 107      * not, then you would mark the cache entry as valid (using MarkValid) and
 108      * then simply read the data from the cache.
 109      *
 110      * A descriptor granted WRITE access has exclusive access to the cache
 111      * entry up to the point at which it marks it as valid.  Once the cache
 112      * entry has been "validated", other descriptors with READ access may be
 113      * opened to the cache entry.
 114      *
 115      * If you make a request for READ_WRITE access to a cache entry, the cache
 116      * service will downgrade your access to READ if there is already a
 117      * cache entry descriptor open with WRITE access.
 118      *
 119      * If you make a request for only WRITE access to a cache entry and another
 120      * descriptor with WRITE access is currently open, then the existing cache
 121      * entry will be 'doomed', and you will be given a descriptor (with WRITE
 122      * access only) to a new cache entry.
 123      *
 124      */
 125     const nsCacheAccessMode ACCESS_NONE       = 0;
 126     const nsCacheAccessMode ACCESS_READ       = 1;
 127     const nsCacheAccessMode ACCESS_WRITE      = 2;
 128     const nsCacheAccessMode ACCESS_READ_WRITE = 3;
 129
 130     /**
 131      * Storage Policy
 132      *
 133      * The storage policy of a cache entry determines the device(s) to which
 134      * it belongs.  See nsICacheSession and nsICacheEntryDescriptor for more
 135      * details.
 136      *
 137      * STORE_ANYWHERE        - Allows the cache entry to be stored in any device.
 138      *                         The cache service decides which cache device to use
 139      *                         based on "some resource management calculation."
 140      * STORE_IN_MEMORY       - Requires the cache entry to reside in non-persistent
 141      *                         storage (ie. typically in system RAM).
 142      * STORE_ON_DISK         - Requires the cache entry to reside in persistent
 143      *                         storage (ie. typically on a system's hard disk).
 144      * STORE_ON_DISK_AS_FILE - Requires the cache entry to reside in persistent
 145      *                         storage, and in a separate file.
 146      * STORE_OFFLINE         - Requires the cache entry to reside in persistent,
 147      *                         reliable storage for offline use.
 148      */
 149     const nsCacheStoragePolicy STORE_ANYWHERE        = 0;
 150     const nsCacheStoragePolicy STORE_IN_MEMORY       = 1;
 151     const nsCacheStoragePolicy STORE_ON_DISK         = 2;
 152     const nsCacheStoragePolicy STORE_ON_DISK_AS_FILE = 3;
 153     const nsCacheStoragePolicy STORE_OFFLINE         = 4;
 154
 155     /**
 156      * All entries for a cache session are stored as streams of data or
 157      * as objects.  These constant my be used to specify the type of entries
 158      * when calling nsICacheService::CreateSession().
 159      */
 160     const long NOT_STREAM_BASED = 0;
 161     const long STREAM_BASED     = 1;
 162
 163     /**
 164      * The synchronous OpenCacheEntry() may be blocking or non-blocking.  If a cache entry is
 165      * waiting to be validated by another cache descriptor (so no new cache descriptors for that
 166      * key can be created, OpenCacheEntry() will return NS_ERROR_CACHE_WAIT_FOR_VALIDATION in
 167      * non-blocking mode.  In blocking mode, it will wait until the cache entry for the key has
 168      * been validated or doomed.  If the cache entry is validated, then a descriptor for that
 169      * entry will be created and returned.  If the cache entry was doomed, then a descriptor
 170      * will be created for a new cache entry for the key.
 171      */
 172     const long NON_BLOCKING = 0;
 173     const long BLOCKING     = 1;
 174 };
 175
 176 %{C++
 177 #include "nsNetError.h"
 178 %}