netwerk/base/nsIProgressEventSink.idl

   1 /* -*- Mode: C++; tab-width: 2; 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 nsIURI;
   9 interface nsIRequest;
  10
  11 /**
  12  * nsIProgressEventSink
  13  *
  14  * This interface is used to asynchronously convey channel status and progress
  15  * information that is generally not critical to the processing of the channel.
  16  * The information is intended to be displayed to the user in some meaningful
  17  * way.
  18  *
  19  * An implementation of this interface can be passed to a channel via the
  20  * channel's notificationCallbacks attribute.  See nsIChannel for more info.
  21  *
  22  * The channel will begin passing notifications to the progress event sink
  23  * after its asyncOpen method has been called.  Notifications will cease once
  24  * the channel calls its listener's onStopRequest method or once the channel
  25  * is canceled (via nsIRequest::cancel).
  26  *
  27  * NOTE: This interface is actually not specific to channels and may be used
  28  * with other implementations of nsIRequest.
  29  */
  30 [scriptable, uuid(87d55fba-cb7e-4f38-84c1-5c6c2b2a55e9)]
  31 interface nsIProgressEventSink : nsISupports
  32 {
  33     /**
  34      * Called to notify the event sink that progress has occurred for the
  35      * given request.
  36      *
  37      * @param aRequest
  38      *        the request being observed (may QI to nsIChannel).
  39      * @param aProgress
  40      *        numeric value in the range 0 to aProgressMax indicating the
  41      *        number of bytes transfered thus far.
  42      * @param aProgressMax
  43      *        numeric value indicating maximum number of bytes that will be
  44      *        transfered (or -1 if total is unknown).
  45      */
  46     void onProgress(in nsIRequest aRequest,
  47                     in long long aProgress,
  48                     in long long aProgressMax);
  49
  50     /**
  51      * Called to notify the event sink with a status message for the given
  52      * request.
  53      *
  54      * @param aRequest
  55      *        the request being observed (may QI to nsIChannel).
  56      * @param aStatus
  57      *        status code (not necessarily an error code) indicating the
  58      *        state of the channel (usually the state of the underlying
  59      *        transport).  see nsISocketTransport for socket specific status
  60      *        codes.
  61      * @param aStatusArg
  62      *        status code argument to be used with the string bundle service
  63      *        to convert the status message into localized, human readable
  64      *        text.  the meaning of this parameter is specific to the value
  65      *        of the status code.  for socket status codes, this parameter
  66      *        indicates the host:port associated with the status code.
  67      */
  68     void onStatus(in nsIRequest aRequest,
  69                   in nsresult aStatus,
  70                   in wstring aStatusArg);
  71
  72 };