netwerk/cache/public/nsICacheEntryDescriptor.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 nsICacheEntryDescriptor.idl, released
  17  * February 10, 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 "nsICacheVisitor.idl"
  44 #include "nsICache.idl"
  45
  46 interface nsISimpleEnumerator;
  47 interface nsICacheListener;
  48 interface nsIInputStream;
  49 interface nsIOutputStream;
  50 interface nsIFile;
  51 interface nsICacheMetaDataVisitor;
  52
  53
  54 [scriptable, uuid(49c1a11d-f5d2-4f09-8262-551e64908ada)]
  55 interface nsICacheEntryDescriptor : nsICacheEntryInfo
  56 {
  57     /**
  58      * Set the time at which the cache entry should be considered invalid (in
  59      * seconds since the Epoch).
  60      */
  61     void setExpirationTime(in PRUint32 expirationTime);
  62
  63     /**
  64      * Set the cache entry data size.  This will fail if the cache entry
  65      * IS stream based.
  66      */
  67     void setDataSize(in unsigned long size);
  68
  69     /**
  70      * Open blocking input stream to cache data.  This will fail if the cache
  71      * entry IS NOT stream based.  Use the stream transport service to
  72      * asynchronously read this stream on a background thread.  The returned
  73      * stream MAY implement nsISeekableStream.
  74      *
  75      * @param offset
  76      *        read starting from this offset into the cached data.  an offset
  77      *        beyond the end of the stream has undefined consequences.
  78      *
  79      * @return blocking, unbuffered input stream.
  80      */
  81     nsIInputStream openInputStream(in unsigned long offset);
  82
  83     /**
  84      * Open blocking output stream to cache data.  This will fail if the cache
  85      * entry IS NOT stream based.  Use the stream transport service to
  86      * asynchronously write to this stream on a background thread.  The returned
  87      * stream MAY implement nsISeekableStream.
  88      *
  89      * If opening an output stream to existing cached data, the data will be
  90      * truncated to the specified offset.
  91      *
  92      * @param offset
  93      *        write starting from this offset into the cached data.  an offset
  94      *        beyond the end of the stream has undefined consequences.
  95      *
  96      * @return blocking, unbuffered output stream.
  97      */
  98     nsIOutputStream openOutputStream(in unsigned long offset);
  99
 100     /**
 101      * Get/set the cache data element.  This will fail if the cache entry
 102      * IS stream based.  The cache entry holds a strong reference to this
 103      * object.  The object will be released when the cache entry is destroyed.
 104      */
 105     attribute nsISupports cacheElement;
 106
 107     /**
 108      * Get the access granted to this descriptor.  See nsICache.idl for the
 109      * definitions of the access modes and a thorough description of their
 110      * corresponding meanings.
 111      */
 112     readonly attribute nsCacheAccessMode accessGranted;
 113
 114     /**
 115      * Get/set the storage policy of the cache entry.  See nsICache.idl for
 116      * the definitions of the storage policies.
 117      */
 118     attribute nsCacheStoragePolicy storagePolicy;
 119
 120     /**
 121      * Get the disk file associated with the cache entry.
 122      */
 123     readonly attribute nsIFile file;
 124
 125     /**
 126      * Get/set security info on the cache entry for this descriptor.  This fails
 127      * if the storage policy is not STORE_IN_MEMORY.
 128      */
 129     attribute nsISupports securityInfo;
 130
 131     /**
 132      * Doom the cache entry this descriptor references in order to slate it for
 133      * removal.  Once doomed a cache entry cannot be undoomed.
 134      *
 135      * A descriptor with WRITE access can doom the cache entry and choose to
 136      * fail pending requests.  This means that pending requests will not get
 137      * a cache descriptor.  This is meant as a tool for clients that wish to
 138      * instruct pending requests to skip the cache.
 139      */
 140     void doom();
 141     void doomAndFailPendingRequests(in nsresult status);
 142
 143     /**
 144      * A writer must validate this cache object before any readers are given
 145      * a descriptor to the object.
 146      */
 147     void markValid();
 148
 149     /**
 150      *  Explicitly close the descriptor (optional).
 151      */
 152
 153     void close();
 154
 155     /**
 156      * Methods for accessing meta data.  Meta data is a table of key/value
 157      * string pairs.  The strings do not have to conform to any particular
 158      * charset, but they must be null terminated.
 159      */
 160     string getMetaDataElement(in string key);
 161     void   setMetaDataElement(in string key, in string value);
 162
 163     /**
 164      * Visitor will be called with key/value pair for each meta data element.
 165      */
 166     void   visitMetaData(in nsICacheMetaDataVisitor  visitor);
 167 };
 168
 169
 170
 171 [scriptable, uuid(22f9a49c-3cf8-4c23-8006-54efb11ac562)]
 172 interface nsICacheMetaDataVisitor : nsISupports
 173 {
 174     /**
 175      * Called for each key/value pair in the meta data for a cache entry
 176      */
 177     boolean visitMetaDataElement(in string  key,
 178                                  in string  value);
 179 };