/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape 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/NPL/
 *
 * 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 mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"

interface nsIURI;
interface nsINetDataCacheRecord;
interface nsISimpleEnumerator;

/**
 * The nsINetDataCache defines the low-level API for a network-data
 * cache, used to cache the responses to network retrieval commands.
 * This interface, along with nsINetDataCacheRecord, is implemented by
 * the memory cache, the file cache and, optionally, by some extension
 * caches.  This interface is essentially a pseudo-private API for the
 * cache manager.  Other clients should never use this interface.
 *
 * Each cache entry may contain both content, e.g. GIF image data, and
 * associated metadata, e.g. HTTP headers.  Each entry is indexed by two
 * different keys: a record id number and a key created by combining the URI
 * with a "secondary key", e.g. HTTP post data.
 *
 * The nsINetDataCache interface is agnostic as to where the data is
 * stored and whether the storage is volatile or persistent.  The
 * memory cache, any disk caches and any extension caches must all
 * implement this interface.
 *
 */
[scriptable, uuid(ccfc58c0-6dde-11d3-90c8-000064657374)]
interface nsINetDataCache : nsISupports
{
	/**
	 * Human-readable description of the cache module, e.g. "Disk Cache"
	 */
	readonly attribute wstring description;
  
    /**
     * Returns true if cached data is available for the given opaque key,
     * even if only partial data is stored.
     */
    boolean contains([size_is(length)] in string key, in PRUint32 length);

    /**
     * Fetch the cache entry record for the given opaque key.  If one does not
     * exist, create a new, empty record.
     */
    nsINetDataCacheRecord getCachedNetData([size_is(length)] in string key,
                                           in PRUint32 length);

    /**
     * Fetch the cache entry record for the given URI using the record ID as a key.
     */
    nsINetDataCacheRecord getCachedNetDataByID(in PRInt32 RecordID);

	/**
	 * False indicates that this cache is entirely bypassed.
	 */
    attribute boolean enabled;

    /**
     * Constants for flags attribute, below
     */

    // Used for extension caches, e.g. a CD-ROM cache
    const long READ_ONLY          = 1 << 0;

    // One of these bits must be set
    const long MEMORY_CACHE       = 1 << 1;
    const long FLAT_FILE_CACHE    = 1 << 2;
    const long FILE_PER_URL_CACHE = 1 << 3;

	/**
	 * See constants defined above.
	 */
	readonly attribute PRUint32 flags;

    /**
     * Total number of URI entries stored in the cache.
     */
    readonly attribute PRUint32 numEntries;

    /**
     * Maximum number of URI entries that may be stored in the cache.
     */
    readonly attribute PRUint32 maxEntries;

    /**
     * Enumerate the URI entries stored in the cache.
     */
    nsISimpleEnumerator newCacheEntryIterator();

	/**
	 * Contains a reference to the next cache in search order.  For the memory
	 * cache, this attribute always references the disk cache.  For the disk
	 * cache, it contains a reference to the first extension cache.
	 */
    attribute nsINetDataCache nextCache;

    /**
     * An estimate of the amount of storage occupied by the cache, in kB.
     * Actual use may be slightly higher than reported due to cache overhead
     * and heap fragmentation (in the memory cache) or block quantization (in
     * the disk cache).
	 */
    readonly attribute PRUint32 storageInUse;

    /**
     * Remove all entries from a writable cache.  This could be used, for
     * example, after a guest ends a browser session.  This is equivalent to
     * setting the cache's Capacity to zero, except that all cache entries,
     * even those in active use, will be deleted.  Also, any global cache
     * database files will be deleted.
	 */
    void removeAll();
};

%{ C++
// ProgID prefix for Components that implement this interface
#define NS_NETWORK_CACHE_PROGID "component://netscape/network/cache"
#define NS_NETWORK_MEMORY_CACHE_PROGID NS_NETWORK_CACHE_PROGID "?name=memory-cache"
#define NS_NETWORK_FLAT_CACHE_PROGID   NS_NETWORK_CACHE_PROGID "?name=flat-cache"
#define NS_NETWORK_FILE_CACHE_PROGID   NS_NETWORK_CACHE_PROGID "?name=file-cache"
%}