gecko-dev/netwerk/cache/public/nsICacheEntryDescriptor.idl

/* -*- 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 nsICacheEntryDescriptor.idl, released
 * February 10, 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 <gordon@netscape.com>
 *    Patrick Beard   <beard@netscape.com>
 *    Darin Fisher    <darin@netscape.com>
 */

#include "nsITransport.idl"
#include "nsICache.idl"

interface nsISimpleEnumerator;
interface nsICacheListener;
interface nsIFile;

[scriptable, uuid(49c1a11d-f5d2-4f09-8262-551e64908ada)]
interface nsICacheEntryDescriptor : nsISupports
{
    /**
     * Get the key identifying the cache entry.
     */
    readonly attribute string key;

    /**
     * Get the number of times the cache entry has been opened.
     */
    readonly attribute long fetchCount;

    /**
     * Get the last time the cache entry was opened.
     */
    readonly attribute PRTime lastFetched;

    /**
     * Get the last time the cache entry was modified.
     */
    readonly attribute PRTime lastModified;

    /**
     * Get the last time the cache entry was marked valid.
     */
    readonly attribute PRTime lastValidated;

    /**
     * Get the expiration time of the cache entry.
     */
    attribute PRTime expirationTime;

    /**
     * Find out whether or not the cache entry is stream based.
     */
    boolean isStreamBased();

    /**
     * Get/set the cache entry data size.  This attribute can only be set if
     * the cache entry IS NOT stream based.
     */
    attribute unsigned long dataSize;

    /**
     * Get a transport to the cache data.  This will fail if the cache entry
     * IS NOT stream based.
     */
    readonly attribute nsITransport transport;

    /**
     * Get/set the cache data element.  This will fail if the cache entry
     * IS stream based.  The cache entry holds a strong reference to this
     * object.  The object will be released when the cache entry is destroyed.
     */
    attribute nsISupports cacheElement;
     
    /**
     * Get the access granted to this descriptor.  See nsICache.idl for the
     * definitions of the access modes and a thorough description of their
     * corresponding meanings.
     */
    readonly attribute nsCacheAccessMode accessGranted;
    
    /**
     * Get/set the storage policy of the cache entry.  See nsICache.idl for
     * the definitions of the storage policies.
     */
    attribute nsCacheStoragePolicy storagePolicy;

    /**
     * Get the disk file associated with the cache entry.
     */
    readonly attribute nsIFile file;

    /**
     * Get/set security info on the cache entry for this descriptor.  This fails
     * if the storage policy is not STORE_IN_MEMORY.
     */
    attribute nsISupports securityInfo;
    
    /**
     * Doom the cache entry this descriptor references in order to slate it for 
     * removal.  Once doomed a cache entry cannot be undoomed.
     *
     * A descriptor with WRITE access can doom the cache entry and choose to
     * fail pending requests.  This means that pending requests will not get
     * a cache descriptor.  This is meant as a tool for clients that wish to
     * instruct pending requests to skip the cache.
     */
    void doom();
    void doomAndFailPendingRequests(in nsresult status);
    
    /**
     * A writer must validate this cache object before any readers are given
     * a descriptor to the object.
     */
    void markValid();

    /**
     *  Explicitly close the descriptor (optional).
     */
    
    void  close();

    /**
     * Methods for accessing meta data.  Meta data is a table of key/value
     * string pairs.  The strings do not have to conform to any particular
     * charset, but they must be null terminated.
     */
    string getMetaDataElement(in string key);
    void   setMetaDataElement(in string key, in string value);
    
    nsISimpleEnumerator getMetaDataEnumerator(); /* todo */
};