netwerk/base/nsICacheInfoChannel.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIOutputStream;
   8 interface nsIInputStream;
   9
  10 %{C++
  11 namespace mozilla {
  12 template<typename... Elements> class Tuple;
  13 } // namespace mozilla
  14 %}
  15
  16 [ref] native ConstPreferenceArray(const nsTArray<mozilla::Tuple<nsCString, nsCString>>);
  17
  18 [scriptable, uuid(1fb8ccf2-5fa5-45ec-bc57-8c8022a5d0d3)]
  19 interface nsIInputStreamReceiver : nsISupports
  20 {
  21   void onInputStreamReady(in nsIInputStream aStream);
  22 };
  23
  24 [scriptable, uuid(72c34415-c6eb-48af-851f-772fa9ee5972)]
  25 interface nsICacheInfoChannel : nsISupports
  26 {
  27   /**
  28    * Get the number of times the cache entry has been opened. This attribute is
  29    * equivalent to nsICachingChannel.cacheToken.fetchCount.
  30    *
  31    * @throws NS_ERROR_NOT_AVAILABLE if the cache entry or the alternate data
  32    *         cache entry cannot be read.
  33    */
  34   readonly attribute int32_t cacheTokenFetchCount;
  35
  36   /**
  37    * Get expiration time from cache token. This attribute is equivalent to
  38    * nsICachingChannel.cacheToken.expirationTime.
  39    */
  40   readonly attribute uint32_t cacheTokenExpirationTime;
  41
  42   /**
  43    * Set/get charset of cache entry. Accessing this attribute is equivalent to
  44    * calling nsICachingChannel.cacheToken.getMetaDataElement("charset") and
  45    * nsICachingChannel.cacheToken.setMetaDataElement("charset").
  46    */
  47   attribute ACString cacheTokenCachedCharset;
  48
  49   /**
  50    * TRUE if this channel's data is being loaded from the cache.  This value
  51    * is undefined before the channel fires its OnStartRequest notification
  52    * and after the channel fires its OnStopRequest notification.
  53    */
  54   boolean isFromCache();
  55
  56   /**
  57    * The unique ID of the corresponding nsICacheEntry from which the response is
  58    * retrieved. By comparing the returned value, we can judge whether the data
  59    * of two distinct nsICacheInfoChannels is from the same nsICacheEntry. This
  60    * scenario could be useful when verifying whether the alternative data from
  61    * one nsICacheInfochannel matches the main data from another one.
  62    *
  63    * Note: NS_ERROR_NOT_AVAILABLE is thrown when a nsICacheInfoChannel has no
  64    * valid corresponding nsICacheEntry.
  65    */
  66   uint64_t getCacheEntryId();
  67
  68   /**
  69    * Set/get the cache key. This integer uniquely identifies the data in
  70    * the cache for this channel.
  71    *
  72    * A cache key retrieved from a particular instance of nsICacheInfoChannel
  73    * could be set on another instance of nsICacheInfoChannel provided the
  74    * underlying implementations are compatible and provided the new
  75    * channel instance was created with the same URI.  The implementation of
  76    * nsICacheInfoChannel would be expected to use the cache entry identified
  77    * by the cache token.  Depending on the value of nsIRequest::loadFlags,
  78    * the cache entry may be validated, overwritten, or simply read.
  79    *
  80    * The cache key may be 0 indicating that the URI of the channel is
  81    * sufficient to locate the same cache entry.  Setting a 0 cache key
  82    * is likewise valid.
  83    */
  84   attribute unsigned long cacheKey;
  85
  86   /**
  87    * Tells the channel to behave as if the LOAD_FROM_CACHE flag has been set,
  88    * but without affecting the loads for the entire loadGroup in case of this
  89    * channel being the default load group's channel.
  90    */
  91   attribute boolean allowStaleCacheContent;
  92
  93   /**
  94    * Calling this method instructs the channel to serve the alternative data
  95    * if that was previously saved in the cache, otherwise it will serve the
  96    * real data.
  97    * @param type
  98    *        a string identifying the alt-data format
  99    * @param contentType
 100    *        the contentType for which the preference applies.
 101    *        an empty contentType means the preference applies for ANY contentType
 102    *
 103    * The method may be called several times, with different type and contentType.
 104    *
 105    * Must be called before AsyncOpen.
 106    */
 107   void preferAlternativeDataType(in ACString type, in ACString contentType);
 108
 109   /**
 110    * Get the preferred alternative data type set by preferAlternativeDataType().
 111    * The returned types stand for the desired data type instead of the type of the
 112    * information retrieved from the network stack.
 113    */
 114   [noscript, notxpcom, nostdcall]
 115   ConstPreferenceArray preferredAlternativeDataTypes();
 116
 117   /**
 118    * Holds the type of the alternative data representation that the channel
 119    * is returning.
 120    * Is empty string if no alternative data representation was requested, or
 121    * if the requested representation wasn't found in the cache.
 122    * Can only be called during or after OnStartRequest.
 123    */
 124   readonly attribute ACString alternativeDataType;
 125
 126   /**
 127    * Sometimes when the channel is delivering alt-data, we may want to somehow
 128    * access the original content too. This method asynchronously opens the
 129    * input stream and delivers it to the receiver.
 130    */
 131   void getOriginalInputStream(in nsIInputStreamReceiver aReceiver);
 132
 133   /**
 134    * Opens and returns an output stream that a consumer may use to save an
 135    * alternate representation of the data.
 136    * Must be called after the OnStopRequest that delivered the real data.
 137    * The consumer may choose to replace the saved alt representation.
 138    * Opening the output stream will fail if there are any open input streams
 139    * reading the already saved alt representation.
 140    *
 141    * @param type
 142    *        type of the alternative data representation
 143    * @param predictedSize
 144    *        Predicted size of the data that will be written. It's used to decide
 145    *        whether the resulting entry would exceed size limit, in which case
 146    *        an error is thrown. If the size isn't known in advance, -1 should be
 147    *        passed.
 148    */
 149   nsIOutputStream openAlternativeOutputStream(in ACString type, in long long predictedSize);
 150 };