tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

nsIIncrementalStreamLoader.idl (4356B)

      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 };