/* -*- 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 nsISimpleEnumerator;
interface nsICachedNetData;
interface nsINetDataCache;
interface nsINetDataDiskCache;
interface nsIURI;
interface nsIFileSpec;

/**
 * The network-response cache manager is partly responsible for the caching of
 * content and associated metadata that has been retrieved via the network.
 * (The remaining responsibility for caching lies with individual network
 * protocol handlers.)
 *
 * The cache manager supervises the actions of individual cache components,
 * such as the memory cache, the disk cache and any extension caches, e.g. a
 * read-only CD-ROM cache.
 *
 * @See nsINetDataCache
 * @See nsICachedNetData
 */
[scriptable, uuid(71c8ab00-6d5c-11d3-90c8-000064657374)]
interface nsINetDataCacheManager : nsISupports
{
    /**
     * Flag for the GetCachedNetData() method: If set, the memory cache is
     * neither searched nor will any data be stored into it.  This might be
     * appropriate, for example, with images, because they have their own
     * cache for storing *decoded* images.
     */
    const unsigned long BYPASS_MEMORY_CACHE       = 1 << 0;

    /**
     * Flag for the GetCachedNetData() method: If set, the disk cache
     * is neither searched nor will any be data stored into it.
     * However, read-only extension caches may be searched.  This
     * might be used to avoid leaving persistent records of secure
     * data.
     */
    const unsigned long BYPASS_PERSISTENT_CACHE   = 1 << 1;

    /**
     * Flag for the GetCachedNetData() method: If set, any stream
     * content is stored in the cache as a single disk file.  Content
     * will not be cached in the memory cache nor is it cached in a
     * flat-file cache database.  This is used to implement the jar
     * protocol handler and to provide the stream-as-file semantics
     * required by the classic bowser plugin API.
     */
    const unsigned long CACHE_AS_FILE             = 1 << 2;

    /**
     * Fetch the cache entry record for the given URI.  If one does not exist,
     * create a new, empty record.  The normal search order for caches is:
     *   + Memory cache
     *   + Disk cache
     *   + File cache (stream-as-file cache)
     *   + All extension caches
     *
     * When writing, data is typically stored in both the memory cache and the
     * disk cache.  Both the search order and this write policy can be modified by
     * setting one or more of the flag argument bits, as defined above.
     *
     * The optionally-NULL secondaryKey argument can be used, e.g. for form
     * post data or for HTTP headers in the case of HTTP.
     */
    nsICachedNetData getCachedNetData(in string uri,
                                      [size_is(secondaryKeyLength)] in string secondaryKey,
                                      in PRUint32 secondaryKeyLength,
                                      in PRUint32 flags);

    /**
     * Returns true if cached content is available for the given URI, even if
     * only partial data is stored.  The flags argument behaves the same as for
     * the GetCachedNetData() method, above.
     */
    boolean contains(in string uri,
                     [size_is(secondaryKeyLength)] in string secondaryKey,
                     in PRUint32 secondaryKeyLength,
                     in PRUint32 flags);

    /**
     * Total number of unexpired URI entries stored in all caches.  This number
     * does not take into account duplicate URIs, e.g. because the memory cache
     * and the disk cache might each contain an entry for the same URI.
     */
    readonly attribute PRUint32 numEntries;

    /**
     * Enumerate the unexpired URI entries stored in all caches.  Some URIs may
     * be enumerated more than once, e.g.  because the the memory cache and the
     * disk cache might each contain an entry for the same URI.
     */
    nsISimpleEnumerator newCacheEntryIterator();

    /*
     * Enumerate all the loaded nsINetDataCache-implementing cache modules.
     * The first module enumerated will be the memory cache, the second will be
     * the disk cache, then the file cache, followed by all the extension
     * caches, in search order. 
     */
    nsISimpleEnumerator newCacheModuleIterator();

    /**
     * Remove all entries from all writable caches.  This could be used, for
     * example, after a guest ends a browser session.  This is equivalent to
     * setting the DiskCacheCapacity 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();

    /**
     * The disk cache is made up of the file cache (for stream-as-file
     * requests) and a (possibly independent) persistent cache that handles all
     * other cache requests.  This attribute sets/gets the combined capacity of
     * these caches, measured in KBytes.  Setting the capacity lower than the
     * current amount of space currently in use may cause cache entries to be
     * evicted from the cache to accomodate the requested capacity.
     */
    attribute PRUint32 diskCacheCapacity;

    /**
     * This attribute sets/gets the capacity of the memory cache, measured in
     * KBytes.  Setting the capacity lower than the current amount of space
     * currently in use may cause cache entries to be evicted from the cache to
     * accomodate the requested capacity.
     */
    attribute PRUint32 memCacheCapacity;

	/**
	 * This attribute must be set before attempting to store into the disk cache.
	 */
    attribute nsIFileSpec diskCacheFolder;
};

%{ C++
// ProgID prefix for Components that implement this interface
#define NS_NETWORK_CACHE_MANAGER_PROGID NS_NETWORK_CACHE_PROGID "?name=manager"
%}