DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (56e7b9127e89)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsICacheVisitor.idl"
#include "nsICache.idl"

interface nsISimpleEnumerator;
interface nsICacheListener;
interface nsIInputStream;
interface nsIOutputStream;
interface nsIFile;
interface nsICacheMetaDataVisitor;


[scriptable, uuid(90b17d31-46aa-4fb1-a206-473c966cbc18)]
interface nsICacheEntryDescriptor : nsICacheEntryInfo
{
    /**
     * Set the time at which the cache entry should be considered invalid (in
     * seconds since the Epoch).
     */
    void setExpirationTime(in uint32_t expirationTime);

    /**
     * Set the cache entry data size.  This will fail if the cache entry
     * IS stream based.
     */
    void setDataSize(in unsigned long size);

    /**
     * Open blocking input stream to cache data.  This will fail if the cache
     * entry IS NOT stream based.  Use the stream transport service to
     * asynchronously read this stream on a background thread.  The returned
     * stream MAY implement nsISeekableStream.
     *
     * @param offset
     *        read starting from this offset into the cached data.  an offset
     *        beyond the end of the stream has undefined consequences.
     *
     * @return blocking, unbuffered input stream.
     */
    nsIInputStream openInputStream(in unsigned long offset);

    /**
     * Open blocking output stream to cache data.  This will fail if the cache
     * entry IS NOT stream based.  Use the stream transport service to
     * asynchronously write to this stream on a background thread.  The returned
     * stream MAY implement nsISeekableStream.
     *
     * If opening an output stream to existing cached data, the data will be
     * truncated to the specified offset.
     *
     * @param offset
     *        write starting from this offset into the cached data.  an offset
     *        beyond the end of the stream has undefined consequences.
     *
     * @return blocking, unbuffered output stream.
     */
    nsIOutputStream openOutputStream(in unsigned long offset);

    /**
     * Get/set the cache data element.  This will fail if the cache entry
     * IS stream based.  The cache entry holds a strong reference to this
     * object.  The object will be released when the cache entry is destroyed.
     */
    attribute nsISupports cacheElement;
    
    /**
      * Stores the Content-Length specified in the HTTP header for this
      * entry. Checked before we write to the cache entry, to prevent ever
      * taking up space in the cache for an entry that we know up front 
      * is going to have to be evicted anyway. See bug 588507.
      */
    attribute int64_t    predictedDataSize;

    /**
     * Get the access granted to this descriptor.  See nsICache.idl for the
     * definitions of the access modes and a thorough description of their
     * corresponding meanings.
     */
    readonly attribute nsCacheAccessMode accessGranted;
    
    /**
     * Get/set the storage policy of the cache entry.  See nsICache.idl for
     * the definitions of the storage policies.
     */
    attribute nsCacheStoragePolicy storagePolicy;

    /**
     * Get the disk file associated with the cache entry.
     */
    readonly attribute nsIFile file;

    /**
     * Get/set security info on the cache entry for this descriptor.  This fails
     * if the storage policy is not STORE_IN_MEMORY.
     */
    attribute nsISupports securityInfo;
    
    /**
     * Get the size of the cache entry data, as stored. This may differ
     * from the entry's dataSize, if the entry is compressed.
     */
    readonly attribute unsigned long storageDataSize;

    /**
     * Doom the cache entry this descriptor references in order to slate it for 
     * removal.  Once doomed a cache entry cannot be undoomed.
     *
     * A descriptor with WRITE access can doom the cache entry and choose to
     * fail pending requests.  This means that pending requests will not get
     * a cache descriptor.  This is meant as a tool for clients that wish to
     * instruct pending requests to skip the cache.
     */
    void doom();
    void doomAndFailPendingRequests(in nsresult status);

    /**
     * Asynchronously doom an entry. Listener will be notified about the status
     * of the operation. Null may be passed if caller doesn't care about the
     * result.
     */
    void asyncDoom(in nsICacheListener listener);

    /**
     * A writer must validate this cache object before any readers are given
     * a descriptor to the object.
     */
    void markValid();

    /**
     *  Explicitly close the descriptor (optional).
     */
    
    void close();

    /**
     * Methods for accessing meta data.  Meta data is a table of key/value
     * string pairs.  The strings do not have to conform to any particular
     * charset, but they must be null terminated.
     */
    string getMetaDataElement(in string key);
    void   setMetaDataElement(in string key, in string value);
    
    /**
     * Visitor will be called with key/value pair for each meta data element.
     */
    void   visitMetaData(in nsICacheMetaDataVisitor  visitor);
};



[scriptable, uuid(22f9a49c-3cf8-4c23-8006-54efb11ac562)]
interface nsICacheMetaDataVisitor : nsISupports
{
    /**
     * Called for each key/value pair in the meta data for a cache entry
     */
    boolean visitMetaDataElement(in string  key,
                                 in string  value);
};