netwerk/base/nsIIncrementalStreamLoader.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 "nsIThreadRetargetableStreamListener.idl"
   7
   8 interface nsIRequest;
   9 interface nsIIncrementalStreamLoader;
  10
  11 [scriptable, uuid(07c3d2cc-5454-4618-9f4f-cd93de9504a4)]
  12 interface nsIIncrementalStreamLoaderObserver : nsISupports
  13 {
  14     /**
  15      * Same as nsIRequestObserver.onStartRequest.
  16      * Called when the loader observes onStartRequest.
  17      *
  18      * @param aRequest request being observed
  19      */
  20     void onStartRequest(in nsIRequest aRequest);
  21
  22     /**
  23      * Called when new data has arrived on the stream.
  24      *
  25      * @param loader the stream loader that loaded the stream.
  26      * @param ctxt the context parameter of the underlying channel
  27      * @param dataLength the length of the new data received
  28      * @param data the contents of the new data received.
  29      *
  30      * This method will always be called asynchronously by the
  31      * nsIIncrementalStreamLoader involved, on the thread that called the
  32      * loader's init() method.
  33      *
  34      * If the observer wants to not accumulate all or portional of the data in
  35      * the internal buffer, the consumedLength shall be set to the value of
  36      * the dataLength or less. By default the consumedLength value is assumed 0.
  37      * The data and dataLength reflect the non-consumed data and will be
  38      * accumulated if consumedLength is not set.
  39      *
  40      * In comparison with onStreamComplete(), the data buffer cannot be
  41      * adopted if this method returns NS_SUCCESS_ADOPTED_DATA.
  42      */
  43     void onIncrementalData(in nsIIncrementalStreamLoader loader,
  44                            in nsISupports ctxt,
  45                            in unsigned long dataLength,
  46                            [const,array,size_is(dataLength)] in octet data,
  47                            inout unsigned long consumedLength);
  48
  49     /**
  50      * Called when the entire stream has been loaded.
  51      *
  52      * @param loader the stream loader that loaded the stream.
  53      * @param ctxt the context parameter of the underlying channel
  54      * @param status the status of the underlying channel
  55      * @param resultLength the length of the data loaded
  56      * @param result the data
  57      *
  58      * This method will always be called asynchronously by the
  59      * nsIIncrementalStreamLoader involved, on the thread that called the
  60      * loader's init() method.
  61      *
  62      * If the observer wants to take over responsibility for the
  63      * data buffer (result), it returns NS_SUCCESS_ADOPTED_DATA
  64      * in place of NS_OK as its success code. The loader will then
  65      * "forget" about the data and not free() it after
  66      * onStreamComplete() returns; observer must call free()
  67      * when the data is no longer required.
  68      */
  69     void onStreamComplete(in nsIIncrementalStreamLoader loader,
  70                           in nsISupports ctxt,
  71                           in nsresult status,
  72                           in unsigned long resultLength,
  73                           [const,array,size_is(resultLength)] in octet result);
  74 };
  75
  76 /**
  77  * Asynchronously loads a channel into a memory buffer.
  78  *
  79  * To use this interface, first call init() with a nsIIncrementalStreamLoaderObserver
  80  * that will be notified when the data has been loaded. Then call asyncOpen()
  81  * on the channel with the nsIIncrementalStreamLoader as the listener. The context
  82  * argument in the asyncOpen() call will be passed to the onStreamComplete()
  83  * callback.
  84  *
  85  * XXX define behaviour for sizes >4 GB
  86  */
  87 [scriptable, uuid(a023b060-ba23-431a-b449-2dd63e220554)]
  88 interface nsIIncrementalStreamLoader : nsIThreadRetargetableStreamListener
  89 {
  90     /**
  91      * Initialize this stream loader, and start loading the data.
  92      *
  93      * @param aObserver
  94      *        An observer that will be notified when the data is complete.
  95      */
  96     void init(in nsIIncrementalStreamLoaderObserver aObserver);
  97
  98     /**
  99      * Gets the number of bytes read so far.
 100      */
 101     readonly attribute unsigned long numBytesRead;
 102
 103     /**
 104      * Gets the request that loaded this file.
 105      * null after the request has finished loading.
 106      */
 107     readonly attribute nsIRequest request;
 108 };