gecko-dev/netwerk/cache/public/nsINetDataCacheRecord.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.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"
#include "nsrootidl.idl"

interface nsIFile;
interface nsIChannel;
interface nsINetDataCache;

/**
 * The nsINetDataCacheRecord represents a single entry in a database that
 * caches data retrieved from the network. On top of this low-level interface
 * to the raw record data, the cache manager implements a higher-level record
 * interface, nsICachedNetData.  Each instance of nsINetDataCacheRecord is
 * (internally) associated with a parent database, an instance of the
 * nsINetDataCache interface.  This interface is essentially a pseudo-private
 * API for the cache manager.  Other clients should never use this interface.
 *
 * Each cache record may contain both content and metadata.  The content may
 * be, for example, GIF image data or HTML, and it is accessed through
 * nsIChannel's streaming API.  The opaque metadata, which may contain HTTP
 * headers among other things, is accessed as a contiguous byte array.  Each
 * entry in the cache is indexed by two different keys: a unique record id
 * number, generated by the cache, and an opaque string.  The latter contains
 * the URI and other secondary key information, e.g. HTTP form post key/value
 * pairs.
 *
 * The nsINetDataCacheRecord interface is agnostic as to where the data is
 * stored and whether the storage is volatile or persistent.  The memory cache,
 * the disk cache, a flat-file cache and any read-only extension caches must
 * all implement this interface.
 *
 * @See nsICachedNetData
 * @See nsINetDataCache
 * @See nsINetDataDiskCache
 * @See nsINetDataCacheManager
 */

interface nsILoadGroup;

[scriptable, uuid(fdcdd6a0-7461-11d3-90ca-0040056a906e)]
interface nsINetDataCacheRecord : nsISupports
{
    /**
     * As far as the nsINetDataCacheRecord implementation is concerned, the
     * cache entry database key is an opaque blob, but it's intended to contain
     * both the URI and any secondary keys, such as HTTP post data.
     */
    void getKey(out unsigned long length, [size_is(length), retval] out string key);

    /**
     * A persistent record number assigned by the cache which must be unique
     * among all entries stored within the same cache.  The record ID serves as
     * an alternate key to the cache record.  Providing that they satisfy the
     * afforementioned uniqueness requirement, record IDs can be assigned any
     * value by the database except that they may never be zero.
     */
    readonly attribute PRInt32 recordID;

    /**
     * Opaque data which can be updated for each cache entry independently of
     * the content data.  This data is a combination of protocol-independent
     * data provided by the cache manager and protocol-specific meta-data,
     * e.g. HTTP headers.
     */
    void getMetaData(out PRUint32 length, [size_is(length), retval] out string metaData);
    void setMetaData(in  PRUint32 length, [size_is(length)] in string data);

    /**
     * Number of content bytes stored in the cache, i.e. via the nsIChannel
     * streaming APIs.  This may be less than the complete content length if a
     * partial cache fill occurred.  Additionally, the cached content can be
     * truncated by reducing the value of this attribute.  When this attribute
     * is set to zero the associated cache disk file, if any, should be
     * deleted.
     */
    attribute PRUint32 storedContentLength;

	/**
	 * Opaque security info associated with the cache entry; it can't be serialized
	 * to disk, so it'll only make sense with memory cache
	 */
	attribute nsISupports securityInfo;

    /** 
     * Delete this cache entry and its associated content.
     */
    void delete();

    /**
     * Create a channel for reading or writing a stream of content into the
     * entry.  However, many of the nsIChannel methods may return
     * NS_NOT_IMPLEMENTED, including:
     *
     *    + GetURI()
     *    + GetContentType()
     *    + GetContentLength()
     */
    nsIChannel newChannel(in nsILoadGroup loadGroup);

    /**
     * If a cache is implemented such that it stores each URI's content in an
     * individual disk file, this method will identify the file corresponding
     * to this record.  This may be used to implement the "stream-as-file"
     * semantics required by some plugins and by the 'jar:' protocol handler.
     * However, not all cache implementations are *required* to store the data
     * from each URI in an individual file, so it is acceptable for an
     * implementation of this method to signal NS_NOT_IMPLEMENTED.
     */
    readonly attribute nsIFile file;
};