Source code

Revision control

Other Tools

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