Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes | Private Member Functions | Private Attributes
nsIncrementalDownload Class Reference
Inheritance diagram for nsIncrementalDownload:
Inheritance graph
[legend]
Collaboration diagram for nsIncrementalDownload:
Collaboration graph
[legend]

List of all members.

Public Member Functions

NS_DECL_ISUPPORTS
NS_DECL_NSIREQUEST
NS_DECL_NSIINCREMENTALDOWNLOAD
NS_DECL_NSIREQUESTOBSERVER
NS_DECL_NSISTREAMLISTENER
NS_DECL_NSIOBSERVER
NS_DECL_NSIINTERFACEREQUESTOR
NS_DECL_NSICHANNELEVENTSINK 
nsIncrementalDownload ()
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.
void onDataAvailable (in nsIRequest aRequest, in nsISupports aContext, in nsIInputStream aInputStream, in unsigned long aOffset, in unsigned long aCount)
 Called when the next chunk of data (corresponding to the request) may be read without blocking the calling thread.
void onStartRequest (in nsIRequest aRequest, in nsISupports aContext)
 Called to signify the beginning of an asynchronous request.
void onStopRequest (in nsIRequest aRequest, in nsISupports aContext, in nsresult aStatusCode)
 Called to signify the end of an asynchronous request.
void observe (in nsISupports aSubject, in string aTopic, in wstring aData)
 Observe will be called when there is a notification for the topic |aTopic|.
void getInterface (in nsIIDRef uuid,[iid_is(uuid), retval] out nsQIResult result)
 Retrieves the specified interface pointer.
void onChannelRedirect (in nsIChannel oldChannel, in nsIChannel newChannel, in unsigned long flags)
 Called when a redirect occurs.

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
const unsigned long REDIRECT_TEMPORARY = 1 << 0
 This is a temporary redirect.
const unsigned long REDIRECT_PERMANENT = 1 << 1
 This is a permanent redirect.
const unsigned long REDIRECT_INTERNAL = 1 << 2
 This is an internal redirect, i.e.

Private Member Functions

 ~nsIncrementalDownload ()
nsresult FlushChunk ()
nsresult CallOnStartRequest ()
void CallOnStopRequest ()
nsresult StartTimer (PRInt32 interval)
nsresult ProcessTimeout ()
nsresult ReadCurrentSize ()
nsresult ClearRequestHeader (nsIHttpChannel *channel, const nsACString &header)

Private Attributes

nsCOMPtr< nsIRequestObservermObserver
nsCOMPtr< nsISupports > mObserverContext
nsCOMPtr< nsIProgressEventSinkmProgressSink
nsCOMPtr< nsIURImURI
nsCOMPtr< nsIURImFinalURI
nsCOMPtr< nsILocalFilemDest
nsCOMPtr< nsIChannelmChannel
nsCOMPtr< nsITimermTimer
nsAutoArrayPtr< char > mChunk
PRInt32 mChunkLen
PRInt32 mChunkSize
PRInt32 mInterval
nsInt64 mTotalSize
nsInt64 mCurrentSize
PRUint32 mLoadFlags
PRInt32 mNonPartialCount
nsresult mStatus
PRPackedBool mIsPending
PRPackedBool mDidOnStartRequest

Detailed Description

Definition at line 121 of file nsIncrementalDownload.cpp.


Constructor & Destructor Documentation

Definition at line 141 of file nsIncrementalDownload.cpp.

{}

Member Function Documentation

Definition at line 209 of file nsIncrementalDownload.cpp.

{
  if (!mObserver || mDidOnStartRequest)
    return NS_OK;

  mDidOnStartRequest = PR_TRUE;
  return mObserver->OnStartRequest(this, mObserverContext);
}

Here is the caller graph for this function:

Definition at line 219 of file nsIncrementalDownload.cpp.

{
  if (!mObserver)
    return;

  // Ensure that OnStartRequest is always called once before OnStopRequest.
  nsresult rv = CallOnStartRequest();
  if (NS_SUCCEEDED(mStatus))
    mStatus = rv;

  mIsPending = PR_FALSE;

  mObserver->OnStopRequest(this, mObserverContext, mStatus);
  mObserver = nsnull;
  mObserverContext = nsnull;
}

Here is the call graph for this function:

Here is the caller graph for this function:

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.

nsresult nsIncrementalDownload::ClearRequestHeader ( nsIHttpChannel channel,
const nsACString &  header 
) [private]

Definition at line 743 of file nsIncrementalDownload.cpp.

{
  NS_ENSURE_ARG(channel);
  return channel->SetRequestHeader(header,
                                   NS_LITERAL_CSTRING(""), PR_FALSE);
}

Here is the caller graph for this function:

Definition at line 187 of file nsIncrementalDownload.cpp.

{
  NS_ASSERTION(mTotalSize != nsInt64(-1), "total size should be known");

  if (mChunkLen == 0)
    return NS_OK;

  nsresult rv = AppendToFile(mDest, mChunk, mChunkLen);
  if (NS_FAILED(rv))
    return rv;

  mCurrentSize += nsInt64(mChunkLen);
  mChunkLen = 0;

  if (mProgressSink)
    mProgressSink->OnProgress(this, mObserverContext,
                              PRUint64(PRInt64(mCurrentSize)),
                              PRUint64(PRInt64(mTotalSize)));
  return NS_OK;
}

Here is the call graph for this function:

void nsIInterfaceRequestor::getInterface ( in nsIIDRef  uuid,
[iid_is(uuid), retval] out nsQIResult  result 
) [inherited]

Retrieves the specified interface pointer.

Parameters:
uuidThe IID of the interface being requested.
result[out] The interface pointer to be filled in if the interface is accessible.
Returns:
NS_OK - interface was successfully returned. NS_NOINTERFACE - interface not accessible. NS_ERROR* - method failure.
void nsIIncrementalDownload::init ( in nsIURI  uri,
in nsIFile  destination,
in long  chunkSize,
in long  intervalInSeconds 
) [inherited]

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 nsIObserver::observe ( in nsISupports  aSubject,
in string  aTopic,
in wstring  aData 
) [inherited]

Observe will be called when there is a notification for the topic |aTopic|.

This assumes that the object implementing this interface has been registered with an observer service such as the nsIObserverService.

If you expect multiple topics/subjects, the impl is responsible for filtering.

You should not modify, add, remove, or enumerate notifications in the implemention of observe.

Parameters:
aSubject: Notification specific interface pointer.
aTopic: The notification topic or subject.
aData: Notification specific wide string. subject event.
void nsIChannelEventSink::onChannelRedirect ( in nsIChannel  oldChannel,
in nsIChannel  newChannel,
in unsigned long  flags 
) [inherited]

Called when a redirect occurs.

This may happen due to an HTTP 3xx status code.

Parameters:
oldChannelThe channel that's being redirected.
newChannelThe new channel. This channel is not opened yet.
flagsFlags indicating the type of redirect. A bitmask consisting of flags from above. One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be set.
Exceptions:
<any>Throwing an exception will cancel the load. No network request for the new channel will be made.
void nsIStreamListener::onDataAvailable ( in nsIRequest  aRequest,
in nsISupports  aContext,
in nsIInputStream  aInputStream,
in unsigned long  aOffset,
in unsigned long  aCount 
) [inherited]

Called when the next chunk of data (corresponding to the request) may be read without blocking the calling thread.

The onDataAvailable impl must read exactly |aCount| bytes of data before returning.

Parameters:
aRequestrequest corresponding to the source of the data
aContextuser defined context
aInputStreaminput stream containing the data chunk
aOffsetNumber of bytes that were sent in previous onDataAvailable calls for this request. In other words, the sum of all previous count parameters. If that number is greater than or equal to 2^32, this parameter will be PR_UINT32_MAX (2^32 - 1).
aCountnumber of bytes available in the stream

NOTE: The aInputStream parameter must implement readSegments.

An exception thrown from onDataAvailable has the side-effect of causing the request to be canceled.

void nsIRequestObserver::onStartRequest ( in nsIRequest  aRequest,
in nsISupports  aContext 
) [inherited]

Called to signify the beginning of an asynchronous request.

Parameters:
aRequestrequest being observed
aContextuser defined context

An exception thrown from onStartRequest has the side-effect of causing the request to be canceled.

Here is the caller graph for this function:

void nsIRequestObserver::onStopRequest ( in nsIRequest  aRequest,
in nsISupports  aContext,
in nsresult  aStatusCode 
) [inherited]

Called to signify the end of an asynchronous request.

This call is always preceded by a call to onStartRequest.

Parameters:
aRequestrequest being observed
aContextuser defined context
aStatusCodereason for stopping (NS_OK if completed successfully)

An exception thrown from onStopRequest is generally ignored.

Here is the caller graph for this function:

Definition at line 248 of file nsIncrementalDownload.cpp.

{
  NS_ASSERTION(!mChannel, "how can we have a channel?");

  // Handle existing error conditions
  if (NS_FAILED(mStatus)) {
    CallOnStopRequest();
    return NS_OK;
  }

  // Fetch next chunk
  
  nsCOMPtr<nsIChannel> channel;
  nsresult rv = NS_NewChannel(getter_AddRefs(channel), mFinalURI, nsnull,
                              nsnull, this, mLoadFlags);
  if (NS_FAILED(rv))
    return rv;

  nsCOMPtr<nsIHttpChannel> http = do_QueryInterface(channel, &rv);
  if (NS_FAILED(rv))
    return rv;

  NS_ASSERTION(mCurrentSize != nsInt64(-1),
      "we should know the current file size by now");

  // We don't support encodings -- they make the Content-Length not equal
  // to the actual size of the data.
  rv = ClearRequestHeader(http, NS_LITERAL_CSTRING("Accept-Encoding"));
  if (NS_FAILED(rv))
    return rv;

  // Don't bother making a range request if we are just going to fetch the
  // entire document.
  if (mInterval || mCurrentSize != nsInt64(0)) {
    nsCAutoString range;
    MakeRangeSpec(mCurrentSize, mTotalSize, mChunkSize, mInterval == 0, range);

    rv = http->SetRequestHeader(NS_LITERAL_CSTRING("Range"), range, PR_FALSE);
    if (NS_FAILED(rv))
      return rv;
  }

  rv = channel->AsyncOpen(this, nsnull);
  if (NS_FAILED(rv))
    return rv;

  // Wait to assign mChannel when we know we are going to succeed.  This is
  // important because we don't want to introduce a reference cycle between
  // mChannel and this until we know for a fact that AsyncOpen has succeeded,
  // thus ensuring that our stream listener methods will be invoked.
  mChannel = channel;
  return NS_OK;
}

Here is the call graph for this function:

Definition at line 304 of file nsIncrementalDownload.cpp.

{
  nsInt64 size;
  nsresult rv = mDest->GetFileSize((PRInt64 *) &size);
  if (rv == NS_ERROR_FILE_NOT_FOUND ||
      rv == NS_ERROR_FILE_TARGET_DOES_NOT_EXIST) {
    mCurrentSize = 0;
    return NS_OK;
  }
  if (NS_FAILED(rv))
    return rv;

  mCurrentSize = size; 
  return NS_OK;
}
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 
) [inherited]

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.

Definition at line 237 of file nsIncrementalDownload.cpp.

{
  nsresult rv;
  mTimer = do_CreateInstance(NS_TIMER_CONTRACTID, &rv);
  if (NS_FAILED(rv))
    return rv;

  return mTimer->Init(this, interval * 1000, nsITimer::TYPE_ONE_SHOT);
}

Here is the call graph for this function:

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.

Definition at line 157 of file nsIncrementalDownload.cpp.

Definition at line 159 of file nsIncrementalDownload.cpp.

Definition at line 160 of file nsIncrementalDownload.cpp.

Definition at line 161 of file nsIncrementalDownload.cpp.

Definition at line 164 of file nsIncrementalDownload.cpp.

Definition at line 156 of file nsIncrementalDownload.cpp.

Definition at line 169 of file nsIncrementalDownload.cpp.

Definition at line 155 of file nsIncrementalDownload.cpp.

Definition at line 162 of file nsIncrementalDownload.cpp.

Definition at line 168 of file nsIncrementalDownload.cpp.

Definition at line 165 of file nsIncrementalDownload.cpp.

Definition at line 166 of file nsIncrementalDownload.cpp.

Definition at line 151 of file nsIncrementalDownload.cpp.

Definition at line 152 of file nsIncrementalDownload.cpp.

Definition at line 153 of file nsIncrementalDownload.cpp.

Definition at line 167 of file nsIncrementalDownload.cpp.

Definition at line 158 of file nsIncrementalDownload.cpp.

Definition at line 163 of file nsIncrementalDownload.cpp.

Definition at line 154 of file nsIncrementalDownload.cpp.

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.

const unsigned long nsIChannelEventSink::REDIRECT_INTERNAL = 1 << 2 [inherited]

This is an internal redirect, i.e.

it was not initiated by the remote server, but is specific to the channel implementation.

The new URI may be identical to the old one.

Definition at line 81 of file nsIChannelEventSink.idl.

const unsigned long nsIChannelEventSink::REDIRECT_PERMANENT = 1 << 1 [inherited]

This is a permanent redirect.

New requests for this resource should use the URI of the new channel (This might be an HTTP 301 reponse). If this flag is not set, this is a temporary redirect.

The new URI may be identical to the old one.

Definition at line 73 of file nsIChannelEventSink.idl.

const unsigned long nsIChannelEventSink::REDIRECT_TEMPORARY = 1 << 0 [inherited]

This is a temporary redirect.

New requests for this resource should continue to use the URI of the old channel.

The new URI may be identical to the old one.

Definition at line 64 of file nsIChannelEventSink.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 class was generated from the following file: