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 nsIAsyncOutputStream;
   8 interface nsIInputStream;
   9
  10 %{C++
  11 #include "nsTArray.h"
  12 namespace mozilla {
  13 namespace net {
  14 class PreferredAlternativeDataTypeParams;
  15 }
  16 } // namespace mozilla
  17 %}
  18
  19 [ref] native ConstPreferredAlternativeDataTypeArray(const nsTArray<mozilla::net::PreferredAlternativeDataTypeParams>);
  20
  21 [scriptable, uuid(1fb8ccf2-5fa5-45ec-bc57-8c8022a5d0d3)]
  22 interface nsIInputStreamReceiver : nsISupports
  23 {
  24   void onInputStreamReady(in nsIInputStream aStream);
  25 };
  26
  27 [scriptable, builtinclass, uuid(72c34415-c6eb-48af-851f-772fa9ee5972)]
  28 interface nsICacheInfoChannel : nsISupports
  29 {
  30   /**
  31    * Get the number of times the cache entry has been opened. This attribute is
  32    * equivalent to nsICachingChannel.cacheToken.fetchCount.
  33    *
  34    * @throws NS_ERROR_NOT_AVAILABLE if the cache entry or the alternate data
  35    *         cache entry cannot be read.
  36    */
  37   readonly attribute uint32_t cacheTokenFetchCount;
  38
  39   /**
  40    * Get expiration time from cache token. This attribute is equivalent to
  41    * nsICachingChannel.cacheToken.expirationTime.
  42    */
  43   readonly attribute uint32_t cacheTokenExpirationTime;
  44
  45   /**
  46    * TRUE if this channel's data is being loaded from the cache.  This value
  47    * is undefined before the channel fires its OnStartRequest notification
  48    * and after the channel fires its OnStopRequest notification.
  49    */
  50   boolean isFromCache();
  51
  52   /**
  53    * Returns true if the channel raced the cache and network requests.
  54    * In order to determine if the response is coming from the cache or the
  55    * network, the consumer can check isFromCache().
  56    * The method can only be called after the channel fires its OnStartRequest
  57    * notification.
  58    */
  59   boolean isRacing();
  60
  61   /**
  62    * The unique ID of the corresponding nsICacheEntry from which the response is
  63    * retrieved. By comparing the returned value, we can judge whether the data
  64    * of two distinct nsICacheInfoChannels is from the same nsICacheEntry. This
  65    * scenario could be useful when verifying whether the alternative data from
  66    * one nsICacheInfochannel matches the main data from another one.
  67    *
  68    * Note: NS_ERROR_NOT_AVAILABLE is thrown when a nsICacheInfoChannel has no
  69    * valid corresponding nsICacheEntry.
  70    */
  71   uint64_t getCacheEntryId();
  72
  73   /**
  74    * Set/get the cache key. This integer uniquely identifies the data in
  75    * the cache for this channel.
  76    *
  77    * A cache key retrieved from a particular instance of nsICacheInfoChannel
  78    * could be set on another instance of nsICacheInfoChannel provided the
  79    * underlying implementations are compatible and provided the new
  80    * channel instance was created with the same URI.  The implementation of
  81    * nsICacheInfoChannel would be expected to use the cache entry identified
  82    * by the cache token.  Depending on the value of nsIRequest::loadFlags,
  83    * the cache entry may be validated, overwritten, or simply read.
  84    *
  85    * The cache key may be 0 indicating that the URI of the channel is
  86    * sufficient to locate the same cache entry.  Setting a 0 cache key
  87    * is likewise valid.
  88    */
  89   attribute unsigned long cacheKey;
  90
  91   /**
  92    * Tells the channel to behave as if the LOAD_FROM_CACHE flag has been set,
  93    * but without affecting the loads for the entire loadGroup in case of this
  94    * channel being the default load group's channel.
  95    */
  96   attribute boolean allowStaleCacheContent;
  97
  98   /**
  99    * Tells the priority for LOAD_CACHE is raised over LOAD_BYPASS_CACHE or
 100    * LOAD_BYPASS_LOCAL_CACHE in case those flags are set at the same time.
 101    */
 102   attribute boolean preferCacheLoadOverBypass;
 103
 104   cenum PreferredAlternativeDataDeliveryType : 8 {
 105     /**
 106      * Do not deliver alternative data stream.
 107      */
 108     NONE = 0,
 109
 110     /**
 111      * Deliver alternative data stream upon additional request.
 112      */
 113     ASYNC = 1,
 114
 115     /**
 116      * Deliver alternative data stream during IPC parent/child serialization.
 117      */
 118     SERIALIZE = 2,
 119   };
 120
 121   /**
 122    * Tells the channel to be force validated during soft reload.
 123    */
 124   attribute boolean forceValidateCacheContent;
 125
 126   /**
 127    * Calling this method instructs the channel to serve the alternative data
 128    * if that was previously saved in the cache, otherwise it will serve the
 129    * real data.
 130    * @param type
 131    *        a string identifying the alt-data format
 132    * @param contentType
 133    *        the contentType for which the preference applies.
 134    *        an empty contentType means the preference applies for ANY contentType
 135    * @param deliverAltData
 136    *        if false, also if alt-data is available, the channel will deliver
 137    *        the original data.
 138    *
 139    * The method may be called several times, with different type and contentType.
 140    *
 141    * Must be called before AsyncOpen.
 142    */
 143   void preferAlternativeDataType(in ACString type, in ACString contentType,
 144                                  in nsICacheInfoChannel_PreferredAlternativeDataDeliveryType deliverAltData);
 145
 146   /**
 147    * Get the preferred alternative data type set by preferAlternativeDataType().
 148    * The returned types stand for the desired data type instead of the type of the
 149    * information retrieved from the network stack.
 150    */
 151   [noscript, notxpcom, nostdcall]
 152   ConstPreferredAlternativeDataTypeArray preferredAlternativeDataTypes();
 153
 154   /**
 155    * Holds the type of the alternative data representation that the channel
 156    * is returning.
 157    * Is empty string if no alternative data representation was requested, or
 158    * if the requested representation wasn't found in the cache.
 159    * Can only be called during or after OnStartRequest.
 160    */
 161   readonly attribute ACString alternativeDataType;
 162
 163   /**
 164    * If preferAlternativeDataType() has been called passing deliverAltData
 165    * equal to false, this attribute will expose the alt-data inputStream if
 166    * avaiable.
 167    */
 168   readonly attribute nsIInputStream alternativeDataInputStream;
 169
 170   /**
 171    * Sometimes when the channel is delivering alt-data, we may want to somehow
 172    * access the original content too. This method asynchronously opens the
 173    * input stream and delivers it to the receiver.
 174    */
 175   void getOriginalInputStream(in nsIInputStreamReceiver aReceiver);
 176
 177   /**
 178    * Opens and returns an output stream that a consumer may use to save an
 179    * alternate representation of the data.
 180    * Must be called after the OnStopRequest that delivered the real data.
 181    * The consumer may choose to replace the saved alt representation.
 182    * Opening the output stream will fail if there are any open input streams
 183    * reading the already saved alt representation. After successfully opening
 184    * an output stream, if there is an error before the entire alt data can be
 185    * written successfully, the client must signal failure by passing an error
 186    * code to CloseWithStatus().
 187    *
 188    * @param type
 189    *        type of the alternative data representation
 190    * @param predictedSize
 191    *        Predicted size of the data that will be written. It's used to decide
 192    *        whether the resulting entry would exceed size limit, in which case
 193    *        an error is thrown. If the size isn't known in advance, -1 should be
 194    *        passed.
 195    */
 196   nsIAsyncOutputStream openAlternativeOutputStream(in ACString type, in long long predictedSize);
 197 };
 198
 199 %{ C++
 200 namespace mozilla {
 201 namespace net {
 202
 203 using PreferredAlternativeDataDeliveryTypeIPC = nsICacheInfoChannel::PreferredAlternativeDataDeliveryType;
 204
 205 }
 206 } // namespace mozilla
 207 %}