зеркало из https://github.com/mozilla/pjs.git
Updated API
This commit is contained in:
fur%netscape.com
Родитель
1741d6d1f1
Коммит
5b94ac83c3
|
|
@ -16,44 +16,54 @@
|
|||
* Reserved.
|
||||
*/
|
||||
|
||||
#include "nsIChannel.idl"
|
||||
#include "nsINetDataCacheRecord.idl"
|
||||
#include "nsrootidl.idl"
|
||||
|
||||
interface nsIFileSpec;
|
||||
interface nsIURI;
|
||||
|
||||
/**
|
||||
* The nsICachedNetData represents a single entry in a cache that implements
|
||||
* the nsINetDataCache interface. It provides access to the cached network
|
||||
* data and metadata, e.g. HTTP headers, for a single URI.
|
||||
* The nsICachedNetData interface represents a single entry in a database that
|
||||
* caches data retrieved from the network. This interface is implemented by the
|
||||
* cache manager on top of the low-level nsINetDataCacheRecord and
|
||||
* nsINetDataCache interfaces that are implemented by the database.
|
||||
*
|
||||
* 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 stored as a byte array. Each entry in the
|
||||
* cache is indexed by two different keys: a record id number and a key created
|
||||
* by combining the URI with a "secondary key", e.g. HTTP post data.
|
||||
*
|
||||
* Though this interface inherits from nsIChannel, it is expected that the
|
||||
* following nsIChannel methods return NS_NOT_IMPLEMENTED:
|
||||
* + GetContentType()
|
||||
* + GetContentLength()
|
||||
*
|
||||
* Though nsIChannel provides for both async and synchronous I/O APIs,
|
||||
* nsIRawCachedNetData need not implement both. If an async I/O method
|
||||
* returns NS_NOT_IMPLEMENTED, the cache manager will fall back to the
|
||||
* synchronous equivalent.
|
||||
*
|
||||
* @See nsICachedNetData
|
||||
* @See nsINetDataCache
|
||||
* @See nsINetDataDiskCache
|
||||
* @See nsINetDataCacheManager
|
||||
*/
|
||||
* @See nsINetDataCacheManager */
|
||||
[scriptable, uuid(6aeb2a40-6d43-11d3-90c8-000064657374)]
|
||||
interface nsICachedNetData : nsIChannel
|
||||
interface nsICachedNetData : nsINetDataCacheRecord
|
||||
{
|
||||
/**
|
||||
* The secondaryKey is combined with the URI (for which an accessor is
|
||||
* defined in the nsIChannel interface), to act as an index into the cache.
|
||||
* The secondaryKey could be, for example, HTTP form post data.
|
||||
* Retrieve the secondary key passed into nsINetDataCache::GetCachedNetData()
|
||||
*/
|
||||
readonly attribute string secondaryKey;
|
||||
[size_is(length)] string GetSecondaryKey(out unsigned long length);
|
||||
|
||||
/**
|
||||
* Opaque, protocol-specific data, e.g. HTTP headers, that can be
|
||||
* updated for each cache entry independently of the content data.
|
||||
* This flag indicates that a protocol handler supports partial fetching of
|
||||
* data. If so, the cache manager may truncate the content to accommodate other
|
||||
* cache entries rather than deleting it wholesale.
|
||||
*/
|
||||
attribute string MetaData;
|
||||
|
||||
/**
|
||||
* Number of content bytes stored in the cache. This may be less
|
||||
* than the complete content length if a partial cache fill
|
||||
* occurred. Also, the cached content can be truncated by
|
||||
* reducing the value of this attribute.
|
||||
*/
|
||||
attribute unsigned long StoredContentLength;
|
||||
|
||||
attribute boolean AllowPartial;
|
||||
|
||||
/**
|
||||
* Indicates that the write stream supplying content data for the cache did
|
||||
* not complete normally, so the content may be truncated.
|
||||
|
|
@ -61,8 +71,10 @@ interface nsICachedNetData : nsIChannel
|
|||
readonly attribute boolean Partial;
|
||||
|
||||
/**
|
||||
* True, if a write stream is open for this cache entry. There can only
|
||||
* be a single write stream open at a time for each cache entry.
|
||||
* True, if a write stream is open for this cache entry or if no
|
||||
* stream data has ever been stored in this cache record. There
|
||||
* can only be a single write stream open at a time for each cache
|
||||
* entry.
|
||||
*/
|
||||
readonly attribute boolean UpdateInProgress;
|
||||
|
||||
|
|
@ -71,50 +83,28 @@ interface nsICachedNetData : nsIChannel
|
|||
*/
|
||||
|
||||
/**
|
||||
* Date/time of expiration for this record, at which point the data and
|
||||
* meta-data are no longer valid and the record may be garbage-collected.
|
||||
* Date/time of expiration for this record, at which point the content is
|
||||
* *likely* to be stale. This heuristic date does not necessarily
|
||||
* correspond to the HTTP Expires header, as it does not determine when
|
||||
* cached network data must be validated with the origin server, but only
|
||||
* serves as a hint to the cache replacement policy.
|
||||
*/
|
||||
readonly attribute PRTime Expiration;
|
||||
readonly attribute PRTime ExpirationTime;
|
||||
|
||||
/**
|
||||
* Date/time of last access (retrieval) of the data in this record.
|
||||
*/
|
||||
readonly attribute PRTime LastRetrieval;
|
||||
readonly attribute PRTime LastRetrievalTime;
|
||||
|
||||
/**
|
||||
* The cache entry last used before this entry was last used.
|
||||
* (The "next least-recently-used" entry.)
|
||||
*/
|
||||
readonly attribute nsICachedNetData NextLRU;
|
||||
|
||||
/**
|
||||
* The cached response with the next closest expiration date (in
|
||||
* the future) to this one
|
||||
*/
|
||||
readonly attribute nsICachedNetData NextToExpire;
|
||||
|
||||
/**
|
||||
* Number of times an output stream has been created for this cache entry
|
||||
* since it was created.
|
||||
* since it was first stored.
|
||||
*/
|
||||
readonly attribute long NumberRetrievals;
|
||||
|
||||
/** True, if a write stream is currently open for this cache entry */
|
||||
readonly attribute boolean CacheFillInProgress;
|
||||
|
||||
/**
|
||||
* Delete this cache entry and its associated content. Any associated open
|
||||
* streams are aborted.
|
||||
*/
|
||||
void Delete();
|
||||
readonly attribute PRUint16 NumberRetrievals;
|
||||
|
||||
/**
|
||||
* When a cache stores each URI's content in a standalone disk file, this
|
||||
* method will identify the corresponding file. This may be used to
|
||||
* implement the "stream-as-file" semantics required by some plugins.
|
||||
* However, no cache is required to store the data from each URI in an
|
||||
* individual file, so it is acceptable for an implementer of this method
|
||||
* to signal NS_NOT_IMPLEMENTED.
|
||||
* If the underlying cache database is persistent, flush this entry's data
|
||||
* to the database.
|
||||
*/
|
||||
readonly attribute nsIFileSpec Filename;
|
||||
void Commit();
|
||||
};
|
||||
|
|
|
|||
|
|
@ -19,17 +19,20 @@
|
|||
#include "nsISupports.idl"
|
||||
|
||||
interface nsIURI;
|
||||
interface nsICachedNetData;
|
||||
interface nsISimpleEnumerator;
|
||||
interface nsINetDataCacheRecord;
|
||||
interface nsIEnumerator;
|
||||
interface nsIFileSpec;
|
||||
|
||||
/**
|
||||
* A network-data cache is used to cache the responses to network
|
||||
* retrieval commands. Each cache entry may contain both content,
|
||||
* e.g. GIF image data, and associated metadata, e.g. HTTP headers.
|
||||
* Each entry in the cache is indexed by a key. This key is a
|
||||
* combination of a URI string and opaque keyData. The latter can be
|
||||
* used, for example, to contain HTTP form post key/value pairs.
|
||||
* The nsINetDataCache defines a network-data cache, used to cache the
|
||||
* responses to network retrieval commands. This interface, along with
|
||||
* nsINetDataCacheRecord, is implemented by the memory cache, the disk cache
|
||||
* and, optionally, by some extension caches.
|
||||
*
|
||||
* Each cache entry may contain both content, e.g. GIF image data, and
|
||||
* associated metadata, e.g. HTTP headers. Each entry is indexed by two
|
||||
* different keys: a record id number and a key created by combining the URI
|
||||
* with a "secondary key", e.g. HTTP post data.
|
||||
*
|
||||
* The nsINetDataCache interface is agnostic as to where the data is
|
||||
* stored and whether the storage is volatile or persistent. The
|
||||
|
|
@ -46,34 +49,28 @@ interface nsINetDataCache : nsISupports
|
|||
readonly attribute wstring Description;
|
||||
|
||||
/**
|
||||
* Returns true if cached data is available for the given URI,
|
||||
* even if only partial data is stored. The optionally-NULL
|
||||
* secondaryKey argument can be used for form post data in the
|
||||
* case of HTTP.
|
||||
* Returns true if cached data is available for the given opaque key,
|
||||
* even if only partial data is stored.
|
||||
*/
|
||||
boolean Contains(in nsIURI uri, in string secondaryKey);
|
||||
boolean Contains([size_is(length)] in string key, in PRUint32 length);
|
||||
|
||||
/**
|
||||
* Fetch the cache entry record for the given URI. If one does not exist,
|
||||
* create a new, empty record.
|
||||
*/
|
||||
nsICachedNetData GetCachedNetData(in nsIURI uri);
|
||||
* Fetch the cache entry record for the given opaque key. If one does not
|
||||
* exist, create a new, empty record.
|
||||
*/
|
||||
nsINetDataCacheRecord GetCachedNetData([size_is(length)] in string key,
|
||||
in PRUint32 length);
|
||||
|
||||
/**
|
||||
* Fetch the cache entry record for the given URI using the record ID as a key.
|
||||
*/
|
||||
nsINetDataCacheRecord GetCachedNetDataByID(in PRInt32 RecordID);
|
||||
|
||||
/**
|
||||
* False indicates that this cache is entirely bypassed.
|
||||
*/
|
||||
attribute boolean enabled;
|
||||
|
||||
/**
|
||||
* The least-recently-used (retrieved) cache entry.
|
||||
*/
|
||||
readonly attribute nsICachedNetData LRU;
|
||||
|
||||
/**
|
||||
* Contains the cache entry with the youngest expiration date
|
||||
*/
|
||||
readonly attribute nsICachedNetData NextToExpire;
|
||||
|
||||
/**
|
||||
* This attribute will be false for the memory cache and the disk cache,
|
||||
* but will be true for all other cache modules.
|
||||
|
|
@ -81,14 +78,19 @@ interface nsINetDataCache : nsISupports
|
|||
readonly attribute boolean ReadOnly;
|
||||
|
||||
/**
|
||||
* Total number of unexpired URI entries stored in the cache.
|
||||
* Total number of URI entries stored in the cache.
|
||||
*/
|
||||
readonly attribute unsigned long NumEntries;
|
||||
readonly attribute PRUint32 NumEntries;
|
||||
|
||||
/**
|
||||
* Enumerate the unexpired URI entries stored in the cache.
|
||||
* Maximum number of URI entries that may be stored in the cache.
|
||||
*/
|
||||
nsISimpleEnumerator EnumerateCacheEntries();
|
||||
readonly attribute PRUint32 MaxEntries;
|
||||
|
||||
/**
|
||||
* Enumerate the URI entries stored in the cache.
|
||||
*/
|
||||
nsIEnumerator NewCacheEntryEnumerator();
|
||||
|
||||
/**
|
||||
* Contains a reference to the next cache in search order. For the memory
|
||||
|
|
@ -103,7 +105,7 @@ interface nsINetDataCache : nsISupports
|
|||
* cause cache entries to be evicted from the cache to accomodate the
|
||||
* requested capacity.
|
||||
*/
|
||||
attribute long Capacity;
|
||||
attribute PRUint32 Capacity;
|
||||
|
||||
/**
|
||||
* An estimate of the amount of storage occupied by the cache, in kB.
|
||||
|
|
@ -111,7 +113,7 @@ interface nsINetDataCache : nsISupports
|
|||
* and heap fragmentation (in the memory cache) or block quantization (in
|
||||
* the disk cache).
|
||||
*/
|
||||
readonly attribute long StorageInUse;
|
||||
readonly attribute PRUint32 StorageInUse;
|
||||
|
||||
/**
|
||||
* Remove all entries from a writable cache. This could be used, for
|
||||
|
|
@ -122,4 +124,3 @@ interface nsINetDataCache : nsISupports
|
|||
*/
|
||||
void RemoveAll();
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@
|
|||
|
||||
#include "nsISupports.idl"
|
||||
|
||||
interface nsISimpleEnumerator;
|
||||
interface nsIEnumerator;
|
||||
interface nsICachedNetData;
|
||||
interface nsINetDataCache;
|
||||
interface nsINetDataDiskCache;
|
||||
|
|
@ -74,35 +74,42 @@ interface nsINetDataCacheManager : nsISupports
|
|||
* The optionally-NULL secondaryKey argument can be used for form
|
||||
* post data in the case of HTTP.
|
||||
*/
|
||||
nsICachedNetData GetCachedNetData(in nsIURI uri, in string secondaryKey, in unsigned long flags);
|
||||
nsICachedNetData GetCachedNetData(in nsIURI uri,
|
||||
[size_is(secondaryKeyLength)] in string secondaryKey,
|
||||
in PRUint32 secondaryKeyLength,
|
||||
in PRUint32 flags);
|
||||
|
||||
/**
|
||||
* Returns true if cached content is available for the given URI, even if
|
||||
* only partial data is stored. The flags argument behaves the same as for
|
||||
* the GetCachedNetData() method, above.
|
||||
*/
|
||||
boolean Contains(in nsIURI uri, in unsigned long flags);
|
||||
boolean Contains(in nsIURI uri,
|
||||
[size_is(secondaryKeyLength)] in string secondaryKey,
|
||||
in PRUint32 secondaryKeyLength,
|
||||
in PRUint32 flags);
|
||||
|
||||
/**
|
||||
* Total number of unexpired URI entries stored in all caches. This number
|
||||
* does not take into account duplicate URIs, e.g. because the memory cache
|
||||
* and the disk cache might each contain an entry for the same URI.
|
||||
*/
|
||||
readonly attribute unsigned long NumEntries;
|
||||
readonly attribute PRUint32 NumEntries;
|
||||
|
||||
/**
|
||||
* Enumerate the unexpired URI entries stored in all caches. Some URIs may
|
||||
* be enumerated more than once, e.g. because the the memory cache and the
|
||||
* disk cache might each contain an entry for the same URI.
|
||||
*/
|
||||
nsISimpleEnumerator EnumerateCacheEntries();
|
||||
nsIEnumerator NewCacheEntryEnumerator();
|
||||
|
||||
/*
|
||||
* Enumerate all the loaded cache modules. The first module enumerated will
|
||||
* be the memory cache, the second will be the disk cache, followed by all
|
||||
* the extension caches, in search order.
|
||||
* Enumerate all the loaded nsINetDataCache-implementing cache
|
||||
* modules. The first module enumerated will be the memory cache,
|
||||
* the second will be the disk cache, followed by all the
|
||||
* extension caches, in search order.
|
||||
*/
|
||||
nsISimpleEnumerator EnumerateCacheModules();
|
||||
nsIEnumerator NewCacheModuleEnumerator();
|
||||
|
||||
/**
|
||||
* Retrieve an interface pointer to the distinguished memory cache.
|
||||
|
|
@ -124,10 +131,9 @@ interface nsINetDataCacheManager : nsISupports
|
|||
void RemoveAll();
|
||||
|
||||
/**
|
||||
* This call may be used to free up memory used by the memory cache under
|
||||
* conditions of high memory pressure. It returns an estimate of the
|
||||
* number of bytes of data free'ed. This method can be invoked from any
|
||||
* thread.
|
||||
* Return the number of times that GetCachedNetData() located an
|
||||
* existing cache entry divided by the number of times
|
||||
* GetCachedNetData was called.
|
||||
*/
|
||||
unsigned long EvictFromMemoryCache(in unsigned long bytesRequested);
|
||||
readonly attribute double HitRatio;
|
||||
};
|
||||
|
|
|
|||
|
|
@ -0,0 +1,113 @@
|
|||
/* -*- 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.0 (the "NPL"); you may not use this file except in
|
||||
* compliance with the NPL. You may obtain a copy of the NPL at
|
||||
* http://www.mozilla.org/NPL/
|
||||
*
|
||||
* Software distributed under the NPL is distributed on an "AS IS" basis,
|
||||
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
|
||||
* for the specific language governing rights and limitations under the
|
||||
* NPL.
|
||||
*
|
||||
* The Initial Developer of this code under the NPL is Netscape
|
||||
* Communications Corporation. Portions created by Netscape are
|
||||
* Copyright (C) 1998 Netscape Communications Corporation. All Rights
|
||||
* Reserved.
|
||||
*/
|
||||
|
||||
#include "nsISupports.idl"
|
||||
#include "nsrootidl.idl"
|
||||
|
||||
interface nsIFileSpec;
|
||||
interface nsIChannel;
|
||||
|
||||
/**
|
||||
* 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 interface,
|
||||
* nsICachedNetData. The parent database implements the nsINetDataCache 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 stored as a byte array. Each entry in the
|
||||
* cache is indexed by two different keys: a record id number and an opaque
|
||||
* string. The latter contains the URI and other secondary key information,
|
||||
* e.g. HTTP form post key/value pairs.
|
||||
*
|
||||
* Though this interface inherits from nsIChannel, it is expected that the
|
||||
* following nsIChannel methods return NS_NOT_IMPLEMENTED:
|
||||
* + GetURI()
|
||||
* + GetContentType()
|
||||
* + GetContentLength()
|
||||
*
|
||||
* Though nsIChannel provides for both async and synchronous I/O APIs,
|
||||
* nsIRawCachedNetData need not implement both. If an async I/O method
|
||||
* returns NS_NOT_IMPLEMENTED, the cache manager will fall back to the
|
||||
* synchronous equivalent.
|
||||
*
|
||||
* 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 and any extension caches must all implement this interface.
|
||||
*
|
||||
* @See nsICachedNetData
|
||||
* @See nsINetDataCache
|
||||
* @See nsINetDataDiskCache
|
||||
* @See nsINetDataCacheManager
|
||||
*/
|
||||
[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.
|
||||
*/
|
||||
[size_is(length)] string GetKey(out unsigned long length);
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
readonly attribute PRInt32 RecordID;
|
||||
|
||||
/**
|
||||
* Opaque, protocol-specific data, e.g. HTTP headers, which can be updated
|
||||
* for each cache entry independently of the content data.
|
||||
*/
|
||||
[size_is(length)] string GetMetaData(out unsigned long length);
|
||||
void SetMetaData([size_is(length)] in string data, in PRUint32 length);
|
||||
|
||||
/**
|
||||
* 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. Also, the cached content can be truncated
|
||||
* by reducing the value of this attribute. When this attribute is set
|
||||
* to zero the associated cache file, if any, should be deleted.
|
||||
*/
|
||||
attribute PRUint32 StoredContentLength;
|
||||
|
||||
/**
|
||||
* Delete this cache entry and its associated content. Any associated open
|
||||
* streams are aborted.
|
||||
*/
|
||||
void Delete();
|
||||
|
||||
/**
|
||||
* 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. However, no cache implementation is
|
||||
* *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 nsIFileSpec Filename;
|
||||
|
||||
/**
|
||||
* Create a channel for reading or writing a stream of content into the entry
|
||||
*/
|
||||
nsIChannel NewChannel();
|
||||
};
|
||||
Загрузка…
Ссылка в новой задаче