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

/* -*- 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 Communicator client code, released
 * March 31, 1998.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation. Portions created by Netscape are
 * Copyright (C) 1999 Netscape Communications Corporation. All
 * Rights Reserved.
 * 
 * Contributor(s): 
 *   Scott Furman, fur@netscape.com
 */
#include "nsrootidl.idl"
#include "nsISupports.idl"

interface nsIFile;
interface nsIStreamAsFileObserver;

/**
 * In addition to enhancing effective network response time via caching, the
 * cache manager serves a second purpose by providing the stream-as-file
 * service required by traditional browser plugins and the jar: protocol
 * handler.  The interface below provides a means for a client to determine the
 * filename associated with a stream and to detect modification/deletion of
 * that file.
 */
[scriptable, uuid(0eedbbf0-92d9-11d3-90d3-0040056a906e)]
interface nsIStreamAsFile : nsISupports
{
    /**
     * Filename containing stream-as-file
     */
    readonly attribute nsIFile file;

    /**
     * Add an observer for this cache record.  When the cache wants to delete
     * or truncate a record, so as to make space for another cache entry's
     * content data, it will call <code>aObserver</code>'s Observe() method,
     * passing the nsIStreamAsFile instance as the <code>aSubject</code>
     * argument and an appropriate message.  If the observer does not wish to
     * inhibit deletion/truncation, it should Release() any references it has to the
     * cache record.
     *
     * @See nsIStreamAsFileObserver
     */
    void addObserver(in nsIStreamAsFileObserver aObserver);

    /**
     * Delete an observer that was added by the AddObserver() method.
     */
    void removeObserver(in nsIStreamAsFileObserver aObserver);
};

/**
 * This interface can be implemented by a client to receive notifications of
 * either modification or deletion of a file created by the cache manager using
 * the stream-as-file semantics.
 */
[scriptable, uuid(a26e27c0-92da-11d3-90d3-0040056a906e)]
interface nsIStreamAsFileObserver : nsISupports
{
    /**
     * Flag bits for argument to observeStreamAsFile() method.
     */
    const long NOTIFY_AVAILABLE    = 1 << 0; // Stream-as-file now available for reading
    const long NOTIFY_ERROR        = 1 << 1; // Error while loading stream / creating file
    const long REQUEST_DELETION    = 1 << 2; // Cache manager wishes to delete/truncate file
    const long INVALIDATE          = 1 << 3; // File is out-of-date

    // Convenience value
    const long MAKE_UNAVAILABLE    = REQUEST_DELETION | INVALIDATE;
    
    /**
     * Receive either a notification or a request concerning a file that has
     * been opened using stream-as-file.  The aMessage and aError arguments
     * have varying values depending on the nature of the notification.
     * aMessage is set to NOTIFY_AVAILABLE when a complete stream has been read
     * and stored on disk in a file.  At that point, and no sooner, may the
     * filename attribute of the associated nsIStreamAsFile be accessed via the
     * associated nsIStreamAsFile interface.  If the aMessage argument is
     * NOTIFY_ERROR, the aError argument contains the relevant error code.  If
     * the aMessage argument is either REQUEST_DELETION or REQUEST_TRUNCATION,
     * the callee should immediately Release() all references to the
     * nsIStreamAsFile (and any references to its associated nsICachedNetData
     * instances), unless it wishes to inhibit the requested file modification.
     * If the aMessage argument is INVALIDATE, the cache manager is replacing
     * the file with a more recent version.  If a client wants to continue
     * using the (now out-of-date) file, it must delete it when it has finished,
     * as the cache manager will effectively relinquished ownership of the
     * file.
     */
    void observeStreamAsFile(in nsIStreamAsFile aStreamAsFile,
                             in PRUint32 aMessage,
                             in nsresult aError);
};