michael@0: /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- michael@0: * 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 "nsICacheVisitor.idl" michael@0: #include "nsICache.idl" michael@0: michael@0: interface nsISimpleEnumerator; michael@0: interface nsICacheListener; michael@0: interface nsIInputStream; michael@0: interface nsIOutputStream; michael@0: interface nsIFile; michael@0: interface nsICacheMetaDataVisitor; michael@0: michael@0: michael@0: [scriptable, uuid(90b17d31-46aa-4fb1-a206-473c966cbc18)] michael@0: interface nsICacheEntryDescriptor : nsICacheEntryInfo 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: * Set the cache entry data size. This will fail if the cache entry michael@0: * IS stream based. michael@0: */ michael@0: void setDataSize(in unsigned long size); michael@0: michael@0: /** michael@0: * Open blocking input stream to cache data. This will fail if the cache michael@0: * entry IS NOT stream based. Use the stream transport service to michael@0: * asynchronously read this stream on a background thread. The returned michael@0: * 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 blocking, unbuffered input stream. michael@0: */ michael@0: nsIInputStream openInputStream(in unsigned long offset); michael@0: michael@0: /** michael@0: * Open blocking output stream to cache data. This will fail if the cache michael@0: * entry IS NOT stream based. Use the stream transport service to michael@0: * asynchronously write to this stream on a background thread. The returned michael@0: * stream 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, unbuffered output stream. michael@0: */ michael@0: nsIOutputStream openOutputStream(in unsigned long offset); michael@0: michael@0: /** michael@0: * Get/set the cache data element. This will fail if the cache entry michael@0: * IS stream based. The cache entry holds a strong reference to this michael@0: * object. The object will be released when the cache entry is destroyed. michael@0: */ michael@0: attribute nsISupports cacheElement; 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 the access granted to this descriptor. See nsICache.idl for the michael@0: * definitions of the access modes and a thorough description of their michael@0: * corresponding meanings. michael@0: */ michael@0: readonly attribute nsCacheAccessMode accessGranted; michael@0: michael@0: /** michael@0: * Get/set the storage policy of the cache entry. See nsICache.idl for michael@0: * the definitions of the storage policies. michael@0: */ michael@0: attribute nsCacheStoragePolicy storagePolicy; michael@0: michael@0: /** michael@0: * Get the disk file associated with the cache entry. michael@0: */ michael@0: readonly attribute nsIFile file; michael@0: michael@0: /** michael@0: * Get/set security info on the cache entry for this descriptor. This fails michael@0: * if the storage policy is not STORE_IN_MEMORY. 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: * Doom the cache entry this descriptor references in order to slate it for michael@0: * removal. Once doomed a cache entry cannot be undoomed. michael@0: * michael@0: * A descriptor with WRITE access can doom the cache entry and choose to michael@0: * fail pending requests. This means that pending requests will not get michael@0: * a cache descriptor. This is meant as a tool for clients that wish to michael@0: * instruct pending requests to skip the cache. michael@0: */ michael@0: void doom(); michael@0: void doomAndFailPendingRequests(in nsresult status); 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 nsICacheListener listener); michael@0: michael@0: /** michael@0: * A writer must validate this cache object before any readers are given michael@0: * a descriptor to the object. michael@0: */ michael@0: void markValid(); michael@0: michael@0: /** michael@0: * Explicitly close the descriptor (optional). michael@0: */ michael@0: michael@0: void close(); 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: * Visitor will be called with key/value pair for each meta data element. michael@0: */ michael@0: void visitMetaData(in nsICacheMetaDataVisitor visitor); michael@0: }; michael@0: michael@0: michael@0: michael@0: [scriptable, uuid(22f9a49c-3cf8-4c23-8006-54efb11ac562)] michael@0: interface nsICacheMetaDataVisitor : nsISupports michael@0: { michael@0: /** michael@0: * Called for each key/value pair in the meta data for a cache entry michael@0: */ michael@0: boolean visitMetaDataElement(in string key, michael@0: in string value); michael@0: };