nsIIncrementalDownload.idl (4390B)
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/. */ 6 7 #include "nsIRequest.idl" 8 9 interface nsIURI; 10 interface nsIFile; 11 interface nsIRequestObserver; 12 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 * @param extraHeaders Additional headers to supply with the HTTP request. 53 */ 54 void init(in nsIURI uri, in nsIFile destination, in long chunkSize, 55 in long intervalInSeconds, in ACString extraHeaders); 56 57 /** 58 * The URI being fetched. 59 */ 60 readonly attribute nsIURI URI; 61 62 /** 63 * The URI being fetched after any redirects have been followed. This 64 * attribute is set just prior to calling OnStartRequest on the observer 65 * passed to the start method. 66 */ 67 readonly attribute nsIURI finalURI; 68 69 /** 70 * The file where the download is being written. 71 */ 72 readonly attribute nsIFile destination; 73 74 /** 75 * The total number of bytes for the requested file. This attribute is set 76 * just prior to calling OnStartRequest on the observer passed to the start 77 * method. 78 * 79 * This attribute has a value of -1 if the total size is unknown. 80 */ 81 readonly attribute long long totalSize; 82 83 /** 84 * The current number of bytes downloaded so far. This attribute is set just 85 * prior to calling OnStartRequest on the observer passed to the start 86 * method. 87 * 88 * This attribute has a value of -1 if the current size is unknown. 89 */ 90 readonly attribute long long currentSize; 91 92 /** 93 * Start the incremental download. 94 * 95 * @param observer 96 * An observer to be notified of various events. OnStartRequest is 97 * called when finalURI and totalSize have been determined or when an 98 * error occurs. OnStopRequest is called when the file is completely 99 * downloaded or when an error occurs. If this object implements 100 * nsIProgressEventSink, then its OnProgress method will be called as 101 * data is written to the destination file. If this object implements 102 * nsIInterfaceRequestor, then it will be assigned as the underlying 103 * channel's notification callbacks, which allows it to provide a 104 * nsIAuthPrompt implementation if needed by the channel, for example. 105 * @param ctxt 106 * User defined object forwarded to the observer's methods. 107 */ 108 void start(in nsIRequestObserver observer, 109 in nsISupports ctxt); 110 };