michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIInputStream;
michael@0: interface nsIOutputStream;
michael@0: interface nsICacheEntryDoomCallback;
michael@0: 
michael@0: // ************************ REMOVE **********************
michael@0: typedef long nsCacheAccessMode;
michael@0: typedef long nsCacheStoragePolicy;
michael@0: 
michael@0: interface nsICacheListener;
michael@0: interface nsIFile;
michael@0: interface nsICacheMetaDataVisitor;
michael@0: 
michael@0: [scriptable, uuid(3058bf1e-5116-41cf-826b-e6981308d414)]
michael@0: interface nsICacheEntry : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Placeholder for the initial value of expiration time.
michael@0:    */
michael@0:   const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;
michael@0: 
michael@0:   /**
michael@0:    * Get the key identifying the cache entry.
michael@0:    */
michael@0:   readonly attribute ACString key;
michael@0: 
michael@0:   /**
michael@0:    * Whether the entry is memory/only or persisted to disk.
michael@0:    * Note: private browsing entries are reported as persistent for consistency
michael@0:    * while are not actually persisted to disk.
michael@0:    */
michael@0:   readonly attribute boolean persistent;
michael@0: 
michael@0:   /**
michael@0:    * Get the number of times the cache entry has been opened.
michael@0:    */
michael@0:   readonly attribute long  fetchCount;
michael@0: 
michael@0:   /**
michael@0:    * Get the last time the cache entry was opened (in seconds since the Epoch).
michael@0:    */
michael@0:   readonly attribute uint32_t  lastFetched;
michael@0: 
michael@0:   /**
michael@0:    * Get the last time the cache entry was modified (in seconds since the Epoch).
michael@0:    */
michael@0:   readonly attribute uint32_t  lastModified;
michael@0: 
michael@0:   /**
michael@0:    * Get the expiration time of the cache entry (in seconds since the Epoch).
michael@0:    */
michael@0:   readonly attribute uint32_t  expirationTime;
michael@0: 
michael@0:   /**
michael@0:    * Set the time at which the cache entry should be considered invalid (in
michael@0:    * seconds since the Epoch).
michael@0:    */
michael@0:   void setExpirationTime(in uint32_t expirationTime);
michael@0: 
michael@0:   /**
michael@0:    * Open blocking input stream to cache data.  Use the stream transport
michael@0:    * service to asynchronously read this stream on a background thread.
michael@0:    * The returned stream MAY implement nsISeekableStream.
michael@0:    *
michael@0:    * @param offset
michael@0:    *        read starting from this offset into the cached data.  an offset
michael@0:    *        beyond the end of the stream has undefined consequences.
michael@0:    *
michael@0:    * @return non-blocking, buffered input stream.
michael@0:    */
michael@0:   nsIInputStream openInputStream(in long long offset);
michael@0: 
michael@0:   /**
michael@0:    * Open non-blocking output stream to cache data.  The returned stream
michael@0:    * MAY implement nsISeekableStream.
michael@0:    *
michael@0:    * If opening an output stream to existing cached data, the data will be
michael@0:    * truncated to the specified offset.
michael@0:    *
michael@0:    * @param offset
michael@0:    *        write starting from this offset into the cached data.  an offset
michael@0:    *        beyond the end of the stream has undefined consequences.
michael@0:    *
michael@0:    * @return blocking, buffered output stream.
michael@0:    */
michael@0:   nsIOutputStream openOutputStream(in long long offset);
michael@0: 
michael@0:   /**
michael@0:     * Stores the Content-Length specified in the HTTP header for this
michael@0:     * entry. Checked before we write to the cache entry, to prevent ever
michael@0:     * taking up space in the cache for an entry that we know up front
michael@0:     * is going to have to be evicted anyway. See bug 588507.
michael@0:     */
michael@0:   attribute int64_t predictedDataSize;
michael@0: 
michael@0:   /**
michael@0:    * Get/set security info on the cache entry for this descriptor.
michael@0:    */
michael@0:   attribute nsISupports securityInfo;
michael@0: 
michael@0:   /**
michael@0:    * Get the size of the cache entry data, as stored. This may differ
michael@0:    * from the entry's dataSize, if the entry is compressed.
michael@0:    */
michael@0:   readonly attribute unsigned long storageDataSize;
michael@0: 
michael@0:   /**
michael@0:    * Asynchronously doom an entry. Listener will be notified about the status
michael@0:    * of the operation. Null may be passed if caller doesn't care about the
michael@0:    * result.
michael@0:    */
michael@0:   void asyncDoom(in nsICacheEntryDoomCallback listener);
michael@0: 
michael@0:   /**
michael@0:    * Methods for accessing meta data.  Meta data is a table of key/value
michael@0:    * string pairs.  The strings do not have to conform to any particular
michael@0:    * charset, but they must be null terminated.
michael@0:    */
michael@0:   string getMetaDataElement(in string key);
michael@0:   void   setMetaDataElement(in string key, in string value);
michael@0: 
michael@0:   /**
michael@0:    * Claims that all metadata on this entry are up-to-date and this entry
michael@0:    * now can be delivered to other waiting consumers.
michael@0:    *
michael@0:    * We need such method since metadata must be delivered synchronously.
michael@0:    */
michael@0:   void metaDataReady();
michael@0: 
michael@0:   /**
michael@0:    * Called by consumer upon 304/206 response from the server.  This marks
michael@0:    * the entry content as positively revalidated.
michael@0:    * Consumer uses this method after the consumer has returned ENTRY_NEEDS_REVALIDATION
michael@0:    * result from onCacheEntryCheck and after successfull revalidation with the server.
michael@0:    */
michael@0:   void setValid();
michael@0: 
michael@0:   /**
michael@0:    * Doom this entry and open a new, empty, entry for write.  Consumer has
michael@0:    * to exchange the entry this method is called on for the newly created.
michael@0:    * Used on 200 responses to conditional requests.
michael@0:    *
michael@0:    * @param aMemoryOnly
michael@0:    *    - whether the entry is to be created as memory/only regardless how
michael@0:    *      the entry being recreated persistence is set
michael@0:    * @returns
michael@0:    *    - an entry that can be used to write to
michael@0:    * @throws
michael@0:    *    - NS_ERROR_NOT_AVAILABLE when the entry cannot be from some reason
michael@0:    *      recreated for write
michael@0:    */
michael@0:   nsICacheEntry recreate([optional] in boolean aMemoryOnly);
michael@0: 
michael@0:   /**
michael@0:    * Returns the length of data this entry holds.
michael@0:    * @throws
michael@0:    *    NS_ERROR_IN_PROGRESS when the write is still in progress.
michael@0:    */
michael@0:   readonly attribute long long dataSize;
michael@0: 
michael@0:   /****************************************************************************
michael@0:    * The following methods might be added to some nsICacheEntryInternal
michael@0:    * interface since we want to remove them as soon as the old cache backend is
michael@0:    * completely removed.
michael@0:    */
michael@0: 
michael@0:   /**
michael@0:    * @deprecated
michael@0:    * FOR BACKWARD COMPATIBILITY ONLY
michael@0:    * When the old cache backend is eventually removed, this method
michael@0:    * can be removed too.
michael@0:    *
michael@0:    * In the new backend: this method is no-op
michael@0:    * In the old backend: this method delegates to nsICacheEntryDescriptor.close()
michael@0:    */
michael@0:   void close();
michael@0: 
michael@0:   /**
michael@0:    * @deprecated
michael@0:    * FOR BACKWARD COMPATIBILITY ONLY
michael@0:    * Marks the entry as valid so that others can use it and get only readonly
michael@0:    * access when the entry is held by the 1st writer.
michael@0:    */
michael@0:   void markValid();
michael@0: 
michael@0:   /**
michael@0:    * @deprecated
michael@0:    * FOR BACKWARD COMPATIBILITY ONLY
michael@0:    * Marks the entry as valid when write access is acquired.
michael@0:    */
michael@0:   void maybeMarkValid();
michael@0: 
michael@0:   /**
michael@0:    * @deprecated
michael@0:    * FOR BACKWARD COMPATIBILITY ONLY / KINDA HACK
michael@0:    * @param aWriteAllowed
michael@0:    *    Consumer indicates whether write to the entry is allowed for it.
michael@0:    *    Depends on implementation how the flag is handled.
michael@0:    * @returns
michael@0:    *    true when write access is acquired for this entry,
michael@0:    *    false otherwise
michael@0:    */
michael@0:   boolean hasWriteAccess(in boolean aWriteAllowed);
michael@0: };