Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes
nsIIncrementalDownload Interface Reference

An incremental download object attempts to fetch a file piecemeal over time in an effort to minimize network bandwidth usage. More...

import "nsIIncrementalDownload.idl";

Inheritance diagram for nsIIncrementalDownload:
Inheritance graph
[legend]
Collaboration diagram for nsIIncrementalDownload:
Collaboration graph
[legend]

List of all members.

Public Member Functions

void init (in nsIURI uri, in nsIFile destination, in long chunkSize, in long intervalInSeconds)
 Initialize the incremental download object.
void start (in nsIRequestObserver observer, in nsISupports ctxt)
 Start the incremental download.
boolean isPending ()
 Indicates whether the request is pending.
void cancel (in nsresult aStatus)
 Cancels the current request.
void suspend ()
 Suspends the current request.
void resume ()
 Resumes the current request.

Public Attributes

readonly attribute nsIURI URI
 The URI being fetched.
readonly attribute nsIURI finalURI
 The URI being fetched after any redirects have been followed.
readonly attribute nsIFile destination
 The file where the download is being written.
readonly attribute long long totalSize
 The total number of bytes for the requested file.
readonly attribute long long currentSize
 The current number of bytes downloaded so far.
readonly attribute AUTF8String name
 The name of the request.
readonly attribute nsresult status
 The error status associated with the request.
attribute nsILoadGroup loadGroup
 The load group of this request.
attribute nsLoadFlags loadFlags
 The load flags of this request.
const unsigned long LOAD_NORMAL = 0
 No special load flags:
const unsigned long LOAD_BACKGROUND = 1 << 0
 Don't deliver status notifications to the nsIProgressEventSink, or keep this load from completing the nsILoadGroup it may belong to.
const unsigned long INHIBIT_CACHING = 1 << 7
 This flag prevents caching of any kind.
const unsigned long INHIBIT_PERSISTENT_CACHING = 1 << 8
 This flag prevents caching on disk (or other persistent media), which may be needed to preserve privacy.
const unsigned long LOAD_BYPASS_CACHE = 1 << 9
 Force an end-to-end download of content data from the origin server.
const unsigned long LOAD_FROM_CACHE = 1 << 10
 Load from the cache, bypassing protocol specific validation logic.
const unsigned long VALIDATE_ALWAYS = 1 << 11
 The following flags control the frequency of cached content validation when neither LOAD_BYPASS_CACHE or LOAD_FROM_CACHE are set.
const unsigned long VALIDATE_NEVER = 1 << 12
const unsigned long VALIDATE_ONCE_PER_SESSION = 1 << 13

Detailed Description

An incremental download object attempts to fetch a file piecemeal over time in an effort to minimize network bandwidth usage.

Canceling a background download does not cause the file on disk to be deleted.

Definition at line 53 of file nsIIncrementalDownload.idl.


Member Function Documentation

void nsIRequest::cancel ( in nsresult  aStatus) [inherited]

Cancels the current request.

This will close any open input or output streams and terminate any async requests. Users should normally pass NS_BINDING_ABORTED, although other errors may also be passed. The error passed in will become the value of the status attribute.

Parameters:
aStatusthe reason for canceling this request.

NOTE: most nsIRequest implementations expect aStatus to be a failure code; however, some implementations may allow aStatus to be a success code such as NS_OK. In general, aStatus should be a failure code.

void nsIIncrementalDownload::init ( in nsIURI  uri,
in nsIFile  destination,
in long  chunkSize,
in long  intervalInSeconds 
)

Initialize the incremental download object.

If the destination file already exists, then only the remaining portion of the file will be fetched.

NOTE: The downloader will create the destination file if it does not already exist. It will create the file with the permissions 0600 if needed. To affect the permissions of the file, consumers of this interface may create an empty file at the specified destination prior to starting the incremental download.

NOTE: Since this class may create a temporary file at the specified destination, it is advisable for the consumer of this interface to specify a file name for the destination that would not tempt the user into double-clicking it. For example, it might be wise to append a file extension like ".part" to the end of the destination to protect users from accidentally running "blah.exe" before it is a complete file.

Parameters:
uriThe URI to fetch.
destinationThe location where the file is to be stored.
chunkSizeThe size of the chunks to fetch. A non-positive value results in the default chunk size being used.
intervalInSecondsThe amount of time to wait between fetching chunks. Pass a negative to use the default interval, or 0 to fetch the remaining part of the file in one chunk.
boolean nsIRequest::isPending ( ) [inherited]

Indicates whether the request is pending.

nsIRequest::isPending is true when there is an outstanding asynchronous event that will make the request no longer be pending. Requests do not necessarily start out pending; in some cases, requests have to be explicitly initiated (e.g. nsIChannel implementations are only pending once asyncOpen returns successfully).

Requests can become pending multiple times during their lifetime.

Returns:
TRUE if the request has yet to reach completion.
FALSE if the request has reached completion (e.g., after OnStopRequest has fired).
Note:
Suspended requests are still considered pending.
void nsIRequest::resume ( ) [inherited]

Resumes the current request.

This may have the effect of re-opening any underlying transport and will resume the delivery of data to any open streams.

void nsIIncrementalDownload::start ( in nsIRequestObserver  observer,
in nsISupports  ctxt 
)

Start the incremental download.

Parameters:
observerAn observer to be notified of various events. OnStartRequest is called when finalURI and totalSize have been determined or when an error occurs. OnStopRequest is called when the file is completely downloaded or when an error occurs. If this object implements nsIProgressEventSink, then its OnProgress method will be called as data is written to the destination file. If this object implements nsIInterfaceRequestor, then it will be assigned as the underlying channel's notification callbacks, which allows it to provide a nsIAuthPrompt implementation if needed by the channel, for example.
ctxtUser defined object forwarded to the observer's methods.
void nsIRequest::suspend ( ) [inherited]

Suspends the current request.

This may have the effect of closing any underlying transport (in order to free up resources), although any open streams remain logically opened and will continue delivering data when the transport is resumed.

NOTE: some implementations are unable to immediately suspend, and may continue to deliver events already posted to an event queue. In general, callers should be capable of handling events even after suspending a request.


Member Data Documentation

The current number of bytes downloaded so far.

This attribute is set just prior to calling OnStartRequest on the observer passed to the start method.

This attribute has a value of -1 if the current size is unknown.

Definition at line 121 of file nsIIncrementalDownload.idl.

The file where the download is being written.

Definition at line 103 of file nsIIncrementalDownload.idl.

The URI being fetched after any redirects have been followed.

This attribute is set just prior to calling OnStartRequest on the observer passed to the start method.

Definition at line 98 of file nsIIncrementalDownload.idl.

const unsigned long nsIRequest::INHIBIT_CACHING = 1 << 7 [inherited]

This flag prevents caching of any kind.

It does not, however, prevent cached content from being used to satisfy this request.

Definition at line 153 of file nsIRequest.idl.

const unsigned long nsIRequest::INHIBIT_PERSISTENT_CACHING = 1 << 8 [inherited]

This flag prevents caching on disk (or other persistent media), which may be needed to preserve privacy.

For HTTPS, this flag is set auto- matically.

Definition at line 160 of file nsIRequest.idl.

const unsigned long nsIRequest::LOAD_BACKGROUND = 1 << 0 [inherited]

Don't deliver status notifications to the nsIProgressEventSink, or keep this load from completing the nsILoadGroup it may belong to.

Definition at line 143 of file nsIRequest.idl.

const unsigned long nsIRequest::LOAD_BYPASS_CACHE = 1 << 9 [inherited]

Force an end-to-end download of content data from the origin server.

This flag is used for a shift-reload.

Definition at line 172 of file nsIRequest.idl.

const unsigned long nsIRequest::LOAD_FROM_CACHE = 1 << 10 [inherited]

Load from the cache, bypassing protocol specific validation logic.

This flag is used when browsing via history. It is not recommended for normal browsing as it may likely violate reasonable assumptions made by the server and confuse users.

Definition at line 180 of file nsIRequest.idl.

const unsigned long nsIRequest::LOAD_NORMAL = 0 [inherited]

No special load flags:

Definition at line 137 of file nsIRequest.idl.

The load flags of this request.

Bits 0-15 are reserved.

When added to a load group, this request's load flags are merged with the load flags of the load group.

Definition at line 128 of file nsIRequest.idl.

The load group of this request.

While pending, the request is a member of the load group. It is the responsibility of the request to implement this policy.

Definition at line 120 of file nsIRequest.idl.

readonly attribute AUTF8String nsIRequest::name [inherited]

The name of the request.

Often this is the URI of the request.

Definition at line 55 of file nsIRequest.idl.

readonly attribute nsresult nsIRequest::status [inherited]

The error status associated with the request.

Definition at line 77 of file nsIRequest.idl.

The total number of bytes for the requested file.

This attribute is set just prior to calling OnStartRequest on the observer passed to the start method.

This attribute has a value of -1 if the total size is unknown.

Definition at line 112 of file nsIIncrementalDownload.idl.

The URI being fetched.

Definition at line 91 of file nsIIncrementalDownload.idl.

const unsigned long nsIRequest::VALIDATE_ALWAYS = 1 << 11 [inherited]

The following flags control the frequency of cached content validation when neither LOAD_BYPASS_CACHE or LOAD_FROM_CACHE are set.

By default, cached content is automatically validated if necessary before reuse.

VALIDATE_ALWAYS forces validation of any cached content independent of its expiration time.

VALIDATE_NEVER disables validation of expired content.

VALIDATE_ONCE_PER_SESSION disables validation of expired content, provided it has already been validated (at least once) since the start of this session.

NOTE TO IMPLEMENTORS: These flags are intended for normal browsing, and they should therefore not apply to content that must be validated before each use. Consider, for example, a HTTP response with a "Cache-control: no-cache" header. According to RFC2616, this response must be validated before it can be taken from a cache. Breaking this requirement could result in incorrect and potentially undesirable side-effects.

Definition at line 204 of file nsIRequest.idl.

const unsigned long nsIRequest::VALIDATE_NEVER = 1 << 12 [inherited]

Definition at line 205 of file nsIRequest.idl.

const unsigned long nsIRequest::VALIDATE_ONCE_PER_SESSION = 1 << 13 [inherited]

Definition at line 206 of file nsIRequest.idl.


The documentation for this interface was generated from the following file: