netwerk/base/nsIThrottledInputChannel.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIInputStream;
   9 interface nsIAsyncInputStream;
  10
  11 /**
  12  * An instance of this interface can be used to throttle the uploads
  13  * of a group of associated channels.
  14  */
  15 [scriptable, uuid(6b4b96fe-3c67-4587-af7b-58b6b17da411)]
  16 interface nsIInputChannelThrottleQueue : nsISupports
  17 {
  18     /**
  19      * Initialize this object with the mean and maximum bytes per
  20      * second that will be allowed.  Neither value may be zero, and
  21      * the maximum must not be less than the mean.
  22      *
  23      * @param aMeanBytesPerSecond
  24      *        Mean number of bytes per second.
  25      * @param aMaxBytesPerSecond
  26      *        Maximum number of bytes per second.
  27      */
  28     void init(in unsigned long aMeanBytesPerSecond, in unsigned long aMaxBytesPerSecond);
  29
  30     /**
  31      * Internal use only. Get the values set by init method.
  32      */
  33     [noscript] readonly attribute unsigned long meanBytesPerSecond;
  34     [noscript] readonly attribute unsigned long maxBytesPerSecond;
  35
  36
  37     /**
  38      * Return the number of bytes that are available to the caller in
  39      * this time slice.
  40      *
  41      * @param aRemaining
  42      *        The number of bytes available to be processed
  43      * @return the number of bytes allowed to be processed during this
  44      *        time slice; this will never be greater than aRemaining.
  45      */
  46     unsigned long available(in unsigned long aRemaining);
  47
  48     /**
  49      * Record a successful read.
  50      *
  51      * @param aBytesRead
  52      *        The number of bytes actually read.
  53      */
  54     void recordRead(in unsigned long aBytesRead);
  55
  56     /**
  57      * Return the number of bytes allowed through this queue.  This is
  58      * the sum of all the values passed to recordRead.  This method is
  59      * primarily useful for testing.
  60      */
  61     unsigned long long bytesProcessed();
  62
  63     /**
  64      * Wrap the given input stream in a new input stream which
  65      * throttles the incoming data.
  66      *
  67      * @param aInputStream the input stream to wrap
  68      * @return a new input stream that throttles the data.
  69      */
  70     nsIAsyncInputStream wrapStream(in nsIInputStream aInputStream);
  71 };
  72
  73 /**
  74  * A throttled input channel can be managed by an
  75  * nsIInputChannelThrottleQueue to limit how much data is sent during
  76  * a given time slice.
  77  */
  78 [scriptable, uuid(0a32a100-c031-45b6-9e8b-0444c7d4a143)]
  79 interface nsIThrottledInputChannel : nsISupports
  80 {
  81     /**
  82      * The queue that manages this channel.  Multiple channels can
  83      * share a single queue.  A null value means that no throttling
  84      * will be done.
  85      */
  86     attribute nsIInputChannelThrottleQueue throttleQueue;
  87 };