/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * 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 the Initial Developer are Copyright (C) 2001
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Darin Fisher <darin@netscape.com> (original author)
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or 
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the NPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

interface nsIFile;

/**
 * A channel may optionally implement this interface to allow clients
 * to effect its behavior with respect to how it uses the cache service.
 *
 * This interface provides:
 *   1) Support for "stream as file" semantics (for JAR and plugins).
 *   2) Support for "pinning" cached data in the cache (for printing and save-as).
 */
[scriptable, uuid(b1f95f5e-ee05-4434-9d34-89a935d7feef)]
interface nsICachingChannel : nsISupports
{
    /**
     * Set/get the cache token... uniquely identifies the data in the cache.
     * Holding a reference to this token prevents the cached data from being
     * removed.  A cache token retrieved from a particular instance of 
     * nsICachingChannel could be set on another instance of nsICachingChannel
     * provided the underlying implementations are compatible.  The implemen-
     * tation of nsICachingChannel would be expected to only read from the
     * cache entry identified by the cache token and not try to validate it.
     *
     * The cache token can be treated as an opaque object; however, it can be
     * QI'd to a nsICacheEntryDescriptor if more detailed information about the
     * cache entry is needed.
     */
    attribute nsISupports cacheToken;

    /**
     * Set/get the cache key... uniquely identifies the data in the cache.
     * Holding a reference to this key DOES NOT prevent the cached data from
     * being removed.  It is otherwise similar to the cacheToken.
     *
     * The fromCacheOnly flag inhibits fetching from the net if the data in the
     * cache has been evicted.  An error of NS_ERROR_DOCUMENT_NOT_CACHED will
     * be sent to the listener's onStopRequest in this case.
     */
    nsISupports getCacheKey();
    void        setCacheKey(in nsISupports cacheKey, in boolean fromCacheOnly);

    /**
     * Specifies whether or not the data should be cached to a file.  This
     * may fail if the disk cache is not present.  The value of this attribute
     * is usually only settable during the processing of a channel's
     * OnStartRequest.  The default value of this attribute depends on the
     * particular implementation of nsICachingChannel.
     */
    attribute boolean cacheAsFile;

    /**
     * Get the "file" where the cached data can be found.  This is valid for
     * as long as a reference to the cache token is held.  This may return
     * an error if cacheAsFile is false.
     */
    readonly attribute nsIFile cacheFile;

    /**
     * TRUE if this channel's data is being loaded from the cache.  This value
     * is undefined before the channel fires its OnStartRequest notification
     * and after the channel fires its OnStopRequest notification.
     */
    boolean isFromCache();
};

%{C++
/**
 * nsresult passed through onStopRequest if the document could not be fetched from the cache.
 */
#define NS_ERROR_DOCUMENT_NOT_CACHED NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 70)
%}

.