Usage of nsIRequest Interface

 Accesses the default load request for the group.  Each time a number
 of requests are added to a group, the defaultLoadRequest may be set
 to indicate that all of the requests are related to a base request.

 The load group inherits its load flags from the default load request.
 If the default load request is NULL, then the group's load flags are
 not changed.

attribute nsIRequest defaultLoadRequest

 Gets the request that loaded this file.
 null after the request has finished loading.

readonly attribute nsIRequest request

 Tells the content handler to take over handling the content. If this
 function succeeds, the URI Loader will leave this request alone, ignoring
 progress notifications. Failure of this method will cause the request to be
 cancelled, unless the error code is NS_ERROR_WONT_HANDLE_CONTENT (see
 below).

 @param aWindowContext
        Window context, used to get things like the current nsIDOMWindow
        for this request. May be null.
 @param aContentType
        The content type of aRequest
 @param aRequest
        A request whose content type is already known.

 @throw NS_ERROR_WONT_HANDLE_CONTENT Indicates that this handler does not
        want to handle this content. A different way for handling this
        content should be tried.

void handleContent(in string aContentType, in nsIInterfaceRequestor aWindowContext, in nsIRequest aRequest)

 Given a chunk of data, determines a MIME type. Information from the given
 request may be used in order to make a better decision.

 @param aRequest The request where this data came from. May be null.
 @param aData Data to check
 @param aLength Length of the data

 @return The content type

 @throw NS_ERROR_NOT_AVAILABLE if no MIME type could be determined.

 @note Implementations should consider the request read-only. Especially,
 they should not attempt to set the content type property that subclasses of
 nsIRequest might offer.

ACString getMIMETypeFromContent(in nsIRequest aRequest, [const, array, size_is(aLength)] in octet aData, in unsigned long aLength)

 Called for each directory entry

 @param request - the request
 @param ctxt - opaque parameter
 @param index - new index to add

void onIndexAvailable(in nsIRequest aRequest, in nsISupports aCtxt, in nsIDirIndex aIndex)

 Called for each information line

 @param request - the request
 @param ctxt - opaque parameter
 @param info - new info to add

void onInformationAvailable(in nsIRequest aRequest, in nsISupports aCtxt, in AString aInfo)

 Loads the given URI.  This method is identical to loadURI(...) except
 that its parameter list is broken out instead of being packaged inside
 of an nsIDocShellLoadInfo object...

 @param aURI            - The URI to load.
 @param aReferrer       - Referring URI
 @param aOwner          - Owner (security principal) 
 @param aInheritOwner   - Flag indicating whether the owner of the current
                          document should be inherited if aOwner is null.
 @param aStopActiveDoc  - Flag indicating whether loading the current
                          document should be stopped.
 @param aWindowTarget   - Window target for the load.
 @param aTypeHint       - A hint as to the content-type of the resulting
                          data.  May be null or empty if no hint.
 @param aPostDataStream - Post data stream (if POSTing)
 @param aHeadersStream  - Stream containing "extra" request headers...
 @param aLoadFlags      - Flags to modify load behaviour. Flags are defined
                          in nsIWebNavigation.
 @param aSHEntry        - Active Session History entry (if loading from SH)

[noscript] void internalLoad(in nsIURI aURI, in nsIURI aReferrer, in nsISupports aOwner, in PRUint32 aFlags, in wstring aWindowTarget, in string aTypeHint, in nsIInputStream aPostDataStream, in nsIInputStream aHeadersStream, in unsigned long aLoadFlags, in nsISHEntry aSHEntry, in boolean firstParty, out nsIDocShell aDocShell, out nsIRequest aRequest)

 Called to signal a download that has completed.

void onDownloadComplete(in nsIDownloader downloader, in nsIRequest request, in nsISupports ctxt, in nsresult status, in nsIFile result)

 Binds an external helper application to a stream listener. The caller
 should pump data into the returned stream listener. When the OnStopRequest
 is issued, the stream listener implementation will launch the helper app
 with this data.
 @param aMimeContentType The content type of the incoming data
 @param aRequest The request corresponding to the incoming data
 @param aWindowContext Use GetInterface to retrieve properties like the
                       dom window or parent window...
                       The service might need this in order to bring up dialogs.
 @param aForceSave True to always save this content to disk, regardless of
                   nsIMIMEInfo and other such influences.
 @return A nsIStreamListener which the caller should pump the data into.

nsIStreamListener doContent(in ACString aMimeContentType, in nsIRequest aRequest, in nsIInterfaceRequestor aWindowContext, in boolean aForceSave)

 Adds a new request to the group.  This will cause the default load
 flags to be applied to the request.  If this is a foreground
 request then the groupObserver's onStartRequest will be called.

 If the request is the default load request or if the default load
 request is null, then the load group will inherit its load flags from
 the request.

void addRequest(in nsIRequest aRequest, in nsISupports aContext)

 Removes a request from the group.  If this is a foreground request
 then the groupObserver's onStopRequest will be called.

 By the time this call ends, aRequest will have been removed from the
 loadgroup, even if this function throws an exception.

void removeRequest(in nsIRequest aRequest, in nsISupports aContext, in nsresult aStatus)

 Called to notify the event sink that progress has occurred for the
 given request.

 @param aRequest
        the request being observed (may QI to nsIChannel).
 @param aContext
        if aRequest is a channel, then this parameter is the listener
        context passed to nsIChannel::asyncOpen.
 @param aProgress
        numeric value in the range 0 to aProgressMax indicating the
        number of bytes transfered thus far.
 @param aProgressMax
        numeric value indicating maximum number of bytes that will be
        transfered (or 0xFFFFFFFFFFFFFFFF if total is unknown).

void onProgress(in nsIRequest aRequest, in nsISupports aContext, in unsigned long long aProgress, in unsigned long long aProgressMax)

 Called to notify the event sink with a status message for the given
 request.

 @param aRequest
        the request being observed (may QI to nsIChannel).
 @param aContext
        if aRequest is a channel, then this parameter is the listener
        context passed to nsIChannel::asyncOpen.
 @param aStatus
        status code (not necessarily an error code) indicating the
        state of the channel (usually the state of the underlying
        transport).  see nsISocketTransport for socket specific status
        codes.
 @param aStatusArg
        status code argument to be used with the string bundle service
        to convert the status message into localized, human readable
        text.  the meaning of this parameter is specific to the value
        of the status code.  for socket status codes, this parameter
        indicates the host:port associated with the status code.

void onStatus(in nsIRequest aRequest, in nsISupports aContext, in nsresult aStatus, in wstring aStatusArg)

 Called to signify the beginning of an asynchronous request.

 @param aRequest request being observed
 @param aContext user defined context

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

void onStartRequest(in nsIRequest aRequest, in nsISupports aContext)

 Called to signify the end of an asynchronous request.  This
 call is always preceded by a call to onStartRequest.

 @param aRequest request being observed
 @param aContext user defined context
 @param aStatusCode reason for stopping (NS_OK if completed successfully)

 An exception thrown from onStopRequest is generally ignored.

void onStopRequest(in nsIRequest aRequest, in nsISupports aContext, in nsresult aStatusCode)

 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.

 @param aRequest request corresponding to the source of the data
 @param aContext user defined context
 @param aInputStream input stream containing the data chunk
 @param aOffset
        Number 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).
 @param aCount number 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 onDataAvailable(in nsIRequest aRequest, in nsISupports aContext, in nsIInputStream aInputStream, in unsigned long aOffset, in unsigned long aCount)

 Notifies the content listener to hook up an nsIStreamListener capable of
 consuming the data stream.

 @param aContentType         Content type of the data.
 @param aIsContentPreferred  Indicates whether the content should be
                             preferred by this listener.
 @param aRequest             Request that is providing the data.
 @param aContentHandler      nsIStreamListener that will consume the data.
                             This should be set to <code>nsnull</code> if
                             this content listener can't handle the content
                             type.

 @return                     <code>true</code> if the consumer wants to
                             handle the load completely by itself.  This
                             causes the URI Loader do nothing else...
                             <code>false</code> if the URI Loader should
                             continue handling the load and call the
                             returned streamlistener's methods. 

boolean doContent(in string aContentType, in boolean aIsContentPreferred, in nsIRequest aRequest, out nsIStreamListener aContentHandler)

 Called when the next chunk of data (corresponding to the
 request) is available.

 @param aRequest request corresponding to the source of the data
 @param aContext user defined context
 @param aData the data chunk

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

void onUnicharDataAvailable(in nsIRequest aRequest, in nsISupports aContext, in AString aData)

 Loads the preferred handler when content of a registered type is about
 to be loaded.
 @param   request
          The nsIRequest for the load of the content

void loadPreferredHandler(in nsIRequest request)

 Called when the location of the window being watched changes.  This is not
 when a load is requested, but rather once it is verified that the load is
 going to occur in the given window.  For instance, a load that starts in a
 window might send progress and status messages for the new site, but it
 will not send the onLocationChange until we are sure that we are loading
 this new page here.

 @param aWebProgress
        The nsIWebProgress instance that fired the notification.
 @param aRequest
        The associated nsIRequest.  This may be null in some cases.
 @param aLocation
        The URI of the location that is being loaded.

void onLocationChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in nsIURI aLocation)

 Notification that the progress has changed for one of the requests
 associated with aWebProgress.  Progress totals are reset to zero when all
 requests in aWebProgress complete (corresponding to onStateChange being
 called with aStateFlags including the STATE_STOP and STATE_IS_WINDOW
 flags).

 @param aWebProgress
        The nsIWebProgress instance that fired the notification.
 @param aRequest
        The nsIRequest that has new progress.
 @param aCurSelfProgress
        The current progress for aRequest.
 @param aMaxSelfProgress
        The maximum progress for aRequest.
 @param aCurTotalProgress
        The current progress for all requests associated with aWebProgress.
 @param aMaxTotalProgress
        The total progress for all requests associated with aWebProgress.

 NOTE: If any progress value is unknown, or if its value would exceed the
 maximum value of type long, then its value is replaced with -1.

 NOTE: If the object also implements nsIWebProgressListener2 and the caller
 knows about that interface, this function will not be called. Instead,
 nsIWebProgressListener2::onProgressChange64 will be called.

void onProgressChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in long aCurSelfProgress, in long aMaxSelfProgress, in long aCurTotalProgress, in long aMaxTotalProgress)

 Notification called for security progress.  This method will be called on
 security transitions (eg HTTP -> HTTPS, HTTPS -> HTTP, FOO -> HTTPS) and
 after document load completion.  It might also be called if an error
 occurs during network loading.

 @param aWebProgress
        The nsIWebProgress instance that fired the notification.
 @param aRequest
        The nsIRequest that has new security state.
 @param aState
        A value composed of the Security State Flags and the Security
        Strength Flags listed above.  Any undefined bits are reserved for
        future use.

 NOTE: These notifications will only occur if a security package is
 installed.

void onSecurityChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in unsigned long aState)

 Notification indicating the state has changed for one of the requests
 associated with aWebProgress.

 @param aWebProgress
        The nsIWebProgress instance that fired the notification
 @param aRequest
        The nsIRequest that has changed state.
 @param aStateFlags
        Flags indicating the new state.  This value is a combination of one
        of the State Transition Flags and one or more of the State Type
        Flags defined above.  Any undefined bits are reserved for future
        use.
 @param aStatus
        Error status code associated with the state change.  This parameter
        should be ignored unless aStateFlags includes the STATE_STOP bit.
        The status code indicates success or failure of the request
        associated with the state change.  NOTE: aStatus may be a success
        code even for server generated errors, such as the HTTP 404 error.
        In such cases, the request itself should be queried for extended
        error information (e.g., for HTTP requests see nsIHttpChannel).

void onStateChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in unsigned long aStateFlags, in nsresult aStatus)

 Notification that the status of a request has changed.  The status message
 is intended to be displayed to the user (e.g., in the status bar of the
 browser).

 @param aWebProgress
        The nsIWebProgress instance that fired the notification.
 @param aRequest
        The nsIRequest that has new status.
 @param aStatus
        This value is not an error code.  Instead, it is a numeric value
        that indicates the current status of the request.  This interface
        does not define the set of possible status codes.  NOTE: Some
        status values are defined by nsITransport and nsISocketTransport.
 @param aMessage
        Localized text corresponding to aStatus.

void onStatusChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in nsresult aStatus, in wstring aMessage)

 Notification that the progress has changed for one of the requests
 associated with aWebProgress.  Progress totals are reset to zero when all
 requests in aWebProgress complete (corresponding to onStateChange being
 called with aStateFlags including the STATE_STOP and STATE_IS_WINDOW
 flags).

 This function is identical to nsIWebProgressListener::onProgressChange,
 except that this function supports 64-bit values.

 @param aWebProgress
        The nsIWebProgress instance that fired the notification.
 @param aRequest
        The nsIRequest that has new progress.
 @param aCurSelfProgress
        The current progress for aRequest.
 @param aMaxSelfProgress
        The maximum progress for aRequest.
 @param aCurTotalProgress
        The current progress for all requests associated with aWebProgress.
 @param aMaxTotalProgress
        The total progress for all requests associated with aWebProgress.

 NOTE: If any progress value is unknown, then its value is replaced with -1.

 @see nsIWebProgressListener2::onProgressChange64

void onProgressChange64(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in long long aCurSelfProgress, in long long aMaxSelfProgress, in long long aCurTotalProgress, in long long aMaxTotalProgress)