Source code

Revision control

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIAsyncOutputStream;
interface nsIInputStream;

%{C++
namespace mozilla {
namespace net {
class PreferredAlternativeDataTypeParams;
}
} // namespace mozilla
%}

[ref] native ConstPreferredAlternativeDataTypeArray(const nsTArray<mozilla::net::PreferredAlternativeDataTypeParams>);

[scriptable, uuid(1fb8ccf2-5fa5-45ec-bc57-8c8022a5d0d3)]
interface nsIInputStreamReceiver : nsISupports
{
  void onInputStreamReady(in nsIInputStream aStream);
};

[scriptable, uuid(72c34415-c6eb-48af-851f-772fa9ee5972)]
interface nsICacheInfoChannel : nsISupports
{
  /**
   * Get the number of times the cache entry has been opened. This attribute is
   * equivalent to nsICachingChannel.cacheToken.fetchCount.
   *
   * @throws NS_ERROR_NOT_AVAILABLE if the cache entry or the alternate data
   *         cache entry cannot be read.
   */
  readonly attribute int32_t cacheTokenFetchCount;

  /**
   * Get expiration time from cache token. This attribute is equivalent to
   * nsICachingChannel.cacheToken.expirationTime.
   */
  readonly attribute uint32_t cacheTokenExpirationTime;

  /**
   * Set/get charset of cache entry. Accessing this attribute is equivalent to
   * calling nsICachingChannel.cacheToken.getMetaDataElement("charset") and
   * nsICachingChannel.cacheToken.setMetaDataElement("charset").
   */
  attribute ACString cacheTokenCachedCharset;

  /**
   * TRUE if this channel's data is being loaded from the cache.  This value
   * is undefined before the channel fires its OnStartRequest notification
   * and after the channel fires its OnStopRequest notification.
   */
  boolean isFromCache();

  /**
   * The unique ID of the corresponding nsICacheEntry from which the response is
   * retrieved. By comparing the returned value, we can judge whether the data
   * of two distinct nsICacheInfoChannels is from the same nsICacheEntry. This
   * scenario could be useful when verifying whether the alternative data from
   * one nsICacheInfochannel matches the main data from another one.
   *
   * Note: NS_ERROR_NOT_AVAILABLE is thrown when a nsICacheInfoChannel has no
   * valid corresponding nsICacheEntry.
   */
  uint64_t getCacheEntryId();

  /**
   * Set/get the cache key. This integer uniquely identifies the data in
   * the cache for this channel.
   *
   * A cache key retrieved from a particular instance of nsICacheInfoChannel
   * could be set on another instance of nsICacheInfoChannel provided the
   * underlying implementations are compatible and provided the new
   * channel instance was created with the same URI.  The implementation of
   * nsICacheInfoChannel would be expected to use the cache entry identified
   * by the cache token.  Depending on the value of nsIRequest::loadFlags,
   * the cache entry may be validated, overwritten, or simply read.
   *
   * The cache key may be 0 indicating that the URI of the channel is
   * sufficient to locate the same cache entry.  Setting a 0 cache key
   * is likewise valid.
   */
  attribute unsigned long cacheKey;

  /**
   * Tells the channel to behave as if the LOAD_FROM_CACHE flag has been set,
   * but without affecting the loads for the entire loadGroup in case of this
   * channel being the default load group's channel.
   */
  attribute boolean allowStaleCacheContent;

  /**
   * Calling this method instructs the channel to serve the alternative data
   * if that was previously saved in the cache, otherwise it will serve the
   * real data.
   * @param type
   *        a string identifying the alt-data format
   * @param contentType
   *        the contentType for which the preference applies.
   *        an empty contentType means the preference applies for ANY contentType
   * @param deliverAltData
   *        if false, also if alt-data is available, the channel will deliver
   *        the original data.
   *
   * The method may be called several times, with different type and contentType.
   *
   * Must be called before AsyncOpen.
   */
  void preferAlternativeDataType(in ACString type, in ACString contentType,
                                 in boolean deliverAltData);

  /**
   * Get the preferred alternative data type set by preferAlternativeDataType().
   * The returned types stand for the desired data type instead of the type of the
   * information retrieved from the network stack.
   */
  [noscript, notxpcom, nostdcall]
  ConstPreferredAlternativeDataTypeArray preferredAlternativeDataTypes();

  /**
   * Holds the type of the alternative data representation that the channel
   * is returning.
   * Is empty string if no alternative data representation was requested, or
   * if the requested representation wasn't found in the cache.
   * Can only be called during or after OnStartRequest.
   */
  readonly attribute ACString alternativeDataType;

  /**
   * If preferAlternativeDataType() has been called passing deliverAltData
   * equal to false, this method will expose the alt-data inputStream if
   * aviable.
   */
  void getAltDataInputStream(in ACString type,
                             in nsIInputStreamReceiver aReceiver);

  /**
   * Sometimes when the channel is delivering alt-data, we may want to somehow
   * access the original content too. This method asynchronously opens the
   * input stream and delivers it to the receiver.
   */
  void getOriginalInputStream(in nsIInputStreamReceiver aReceiver);

  /**
   * Opens and returns an output stream that a consumer may use to save an
   * alternate representation of the data.
   * Must be called after the OnStopRequest that delivered the real data.
   * The consumer may choose to replace the saved alt representation.
   * Opening the output stream will fail if there are any open input streams
   * reading the already saved alt representation. After successfully opening
   * an output stream, if there is an error before the entire alt data can be
   * written successfully, the client must signal failure by passing an error
   * code to CloseWithStatus().
   *
   * @param type
   *        type of the alternative data representation
   * @param predictedSize
   *        Predicted size of the data that will be written. It's used to decide
   *        whether the resulting entry would exceed size limit, in which case
   *        an error is thrown. If the size isn't known in advance, -1 should be
   *        passed.
   */
  nsIAsyncOutputStream openAlternativeOutputStream(in ACString type, in long long predictedSize);
};