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