netwerk/base/public/nsIIncrementalDownload.idl@b8a032363ba2
netwerk/base/public/nsIIncrementalDownload.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
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/. */
7 #include "nsIRequest.idl"
9 interface nsIURI;
10 interface nsIFile;
11 interface nsIRequestObserver;
13 /**
14 * An incremental download object attempts to fetch a file piecemeal over time
15 * in an effort to minimize network bandwidth usage.
16 *
17 * Canceling a background download does not cause the file on disk to be
18 * deleted.
19 */
20 [scriptable, uuid(6687823f-56c4-461d-93a1-7f6cb7dfbfba)]
21 interface nsIIncrementalDownload : nsIRequest
22 {
23 /**
24 * Initialize the incremental download object. If the destination file
25 * already exists, then only the remaining portion of the file will be
26 * fetched.
27 *
28 * NOTE: The downloader will create the destination file if it does not
29 * already exist. It will create the file with the permissions 0600 if
30 * needed. To affect the permissions of the file, consumers of this
31 * interface may create an empty file at the specified destination prior to
32 * starting the incremental download.
33 *
34 * NOTE: Since this class may create a temporary file at the specified
35 * destination, it is advisable for the consumer of this interface to specify
36 * a file name for the destination that would not tempt the user into
37 * double-clicking it. For example, it might be wise to append a file
38 * extension like ".part" to the end of the destination to protect users from
39 * accidentally running "blah.exe" before it is a complete file.
40 *
41 * @param uri
42 * The URI to fetch.
43 * @param destination
44 * The location where the file is to be stored.
45 * @param chunkSize
46 * The size of the chunks to fetch. A non-positive value results in
47 * the default chunk size being used.
48 * @param intervalInSeconds
49 * The amount of time to wait between fetching chunks. Pass a
50 * negative to use the default interval, or 0 to fetch the remaining
51 * part of the file in one chunk.
52 */
53 void init(in nsIURI uri, in nsIFile destination, in long chunkSize,
54 in long intervalInSeconds);
56 /**
57 * The URI being fetched.
58 */
59 readonly attribute nsIURI URI;
61 /**
62 * The URI being fetched after any redirects have been followed. This
63 * attribute is set just prior to calling OnStartRequest on the observer
64 * passed to the start method.
65 */
66 readonly attribute nsIURI finalURI;
68 /**
69 * The file where the download is being written.
70 */
71 readonly attribute nsIFile destination;
73 /**
74 * The total number of bytes for the requested file. This attribute is set
75 * just prior to calling OnStartRequest on the observer passed to the start
76 * method.
77 *
78 * This attribute has a value of -1 if the total size is unknown.
79 */
80 readonly attribute long long totalSize;
82 /**
83 * The current number of bytes downloaded so far. This attribute is set just
84 * prior to calling OnStartRequest on the observer passed to the start
85 * method.
86 *
87 * This attribute has a value of -1 if the current size is unknown.
88 */
89 readonly attribute long long currentSize;
91 /**
92 * Start the incremental download.
93 *
94 * @param observer
95 * An observer to be notified of various events. OnStartRequest is
96 * called when finalURI and totalSize have been determined or when an
97 * error occurs. OnStopRequest is called when the file is completely
98 * downloaded or when an error occurs. If this object implements
99 * nsIProgressEventSink, then its OnProgress method will be called as
100 * data is written to the destination file. If this object implements
101 * nsIInterfaceRequestor, then it will be assigned as the underlying
102 * channel's notification callbacks, which allows it to provide a
103 * nsIAuthPrompt implementation if needed by the channel, for example.
104 * @param ctxt
105 * User defined object forwarded to the observer's methods.
106 */
107 void start(in nsIRequestObserver observer,
108 in nsISupports ctxt);
109 };
