netwerk/base/nsIThreadRetargetableStreamListener.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8 #include "nsIStreamListener.idl"
   9 /**
  10  * nsIThreadRetargetableStreamListener
  11  *
  12  * To be used by classes which implement nsIStreamListener and whose
  13  * OnDataAvailable callback may be retargeted for delivery off the main thread.
  14  */
  15 [scriptable, uuid(fb2304b8-f82f-4433-af68-d874a2ebbdc1)]
  16 interface nsIThreadRetargetableStreamListener : nsIStreamListener
  17 {
  18   /**
  19    * Checks this listener and any next listeners it may have to verify that
  20    * they can receive OnDataAvailable off the main thread. It is the
  21    * responsibility of the implementing class to decide on the criteria to
  22    * determine if retargeted delivery of these methods is possible, but it must
  23    * check any and all nsIStreamListener objects that might be called in the
  24    * listener chain.
  25    *
  26    * An exception should be thrown if a listener in the chain does not
  27    * support retargeted delivery, i.e. if the next listener does not implement
  28    * nsIThreadRetargetableStreamListener, or a call to its checkListenerChain()
  29    * fails.
  30    */
  31   void checkListenerChain();
  32
  33   /**
  34    * Used for notifying listeners about data stop.
  35    * After this notification, the listeners could potentially start processing
  36    * the data. Note that onDataFinished can be called on or off the main thread.
  37    * It is the responsibility of the listeners to handle this correctly.
  38    *
  39    * The ChannelEventQueue implementation ensures that the OnDataFinished is
  40    * run on the ODA target thread after the last OnDataAvailable is executed on
  41    * the ODA target thread and before OnStopRequest is called.
  42    * Hence, the following order is guaranteed for the listeners, even with ODA/ODF running off MainThread.
  43    * 1. OnStartRequest
  44    * 2. OnDataAvailable
  45    * 3. OnDataFinished
  46    * 4. OnStopRequest
  47    */
  48   void onDataFinished(in nsresult aStatusCode);
  49 };