Usage of nsIChannel Interface

 Gets the channel for the currently loaded document, if any. 
 For a new document load, this will be the channel of the previous document
 until after OnLocationChange fires.

readonly attribute nsIChannel currentDocumentChannel

 readonly attribute to access the underlying channel

readonly attribute nsIChannel baseChannel

 Returns the base channel that will be used to verify the URI.

readonly attribute nsIChannel baseChannel

 The channel attribute is only valid inside the onDetermineCharset
 and onStreamComplete callbacks.  Otherwise it will be null.

readonly attribute nsIChannel channel

 The request uses a channel in order to perform the
 request.  This attribute represents the channel used
 for the request.  NULL if the channel has not yet been
 created.

 In a multipart request case, this is the initial channel, not the
 different parts in the multipart request.

 Mozilla only. Requires elevated privileges to access.

readonly attribute nsIChannel channel

 Constructs a new channel for the about protocol module. 

 @param aURI the uri of the new channel

nsIChannel newChannel(in nsIURI aURI)

 Equivalent to newChannelFromURI(newURI(...))

nsIChannel newChannel(in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI)

 Creates a channel for a given URI.

 @param aURI nsIURI from which to make a channel
 @return reference to the new nsIChannel object

nsIChannel newChannelFromURI(in nsIURI aURI)

 Constructs a new channel from the given URI for this protocol handler. 

nsIChannel newChannel(in nsIURI aURI)

 Create a new channel with the given proxyInfo

nsIChannel newProxiedChannel(in nsIURI uri, in nsIProxyInfo proxyInfo)

 Start the load and decode of an image.
 @param aChannel the channel to load the image from.  This must
                 already be opened before ths method is called, and there
                 must have been no OnDataAvailable calls for it yet.   
 @param aObserver the observer
 @param cx some random data
 @param aListener [out]
        A listener that should receive the data. Can be null, in which
        case imagelib has found a cached image and is not interested in
        the data. The caller needs not cancel the channel in this case.

 libpr0n does NOT keep a strong ref to the observer; this prevents
 reference cycles.  This means that callers of loadImageWithChannel should
 make sure to Cancel() the resulting request before the observer goes away.

[noscript] imgIRequest loadImageWithChannel(in nsIChannel aChannel, in imgIDecoderObserver aObserver, in nsISupports cx, out nsIStreamListener aListener)

 Asynchronously prompt the user for a username and password.
 This has largely the same semantics as promptUsernameAndPassword(),
 but must return immediately after calling and return the entered
 data in a callback.

 If the user closes the dialog using a cancel button or similar,
 the callback's nsIAuthPromptCallback::onAuthCancelled method must be
 called.
 Calling nsICancelable::cancel on the returned object SHOULD close the
 dialog and MUST call nsIAuthPromptCallback::onAuthCancelled on the provided
 callback.

 @throw NS_ERROR_NOT_IMPLEMENTED
        Asynchronous authentication prompts are not supported;
        the caller should fall back to promptUsernameAndPassword().

nsICancelable asyncPromptAuth(in nsIChannel aChannel, in nsIAuthPromptCallback aCallback, in nsISupports aContext, in PRUint32 level, in nsIAuthInformation authInfo)

 Requests a username and a password. Implementations will commonly show a
 dialog with a username and password field, depending on flags also a
 domain field.

 @param aChannel
        The channel that requires authentication.
 @param level
        One of the level constants from above. See there for descriptions
        of the levels.
 @param authInfo
        Authentication information object. The implementation should fill in
        this object with the information entered by the user before
        returning.

 @retval true
         Authentication can proceed using the values in the authInfo
         object.
 @retval false
         Authentication should be cancelled, usually because the user did
         not provide username/password.

 @note   Exceptions thrown from this function will be treated like a
         return value of false.

boolean promptAuth(in nsIChannel aChannel, in PRUint32 level, in nsIAuthInformation authInfo)

 Checks a channel against the URI classifier service (if it exists).

 The channel will be suspended while the classifier is checked.  The
 channel may be cancelled with an error code determined by the classifier
 before it is resumed.

 If there is no URI classifier service, NS_ERROR_FACTORY_NOT_REGISTERED
 will be returned.

 This method must be called immediately after AsyncOpen() has been called
 on the channel.

 @param aChannel
        The channel to suspend.
 @param aInstallListener
        If true, the classifier will install notification
        callbacks to listen for redirects.  The classifier will
        pass all notifications on to the channel's existing
        notification callbacks.

void start(in nsIChannel aChannel, in boolean aInstallListener)

 Notify the classifier that the channel was redirected.  The new channel
 will be suspended pending a new classifier lookup.

 @param aOldChannel
        The channel that's being redirected.
 @param aNewChannel
        The new channel. This channel is not opened yet.

void onRedirect(in nsIChannel aOldChannel, in nsIChannel aNewChannel)

 Notify the classifier that the channel was redirected.  The new channel
 will be suspended pending a new classifier lookup.

 @param aOldChannel
        The channel that's being redirected.
 @param aNewChannel
        The new channel. This channel is not opened yet.

void onRedirect(in nsIChannel aOldChannel, in nsIChannel aNewChannel)

 Called when a redirect occurs. This may happen due to an HTTP 3xx status
 code.

 @param oldChannel
        The channel that's being redirected.
 @param newChannel
        The new channel. This channel is not opened yet.
 @param flags
        Flags indicating the type of redirect. A bitmask consisting
        of flags from above.
        One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be
        set.

 @throw <any> Throwing an exception will cancel the load. No network
 request for the new channel will be made.

void onChannelRedirect(in nsIChannel oldChannel, in nsIChannel newChannel, in unsigned long flags)

 Called when a redirect occurs. This may happen due to an HTTP 3xx status
 code.

 @param oldChannel
        The channel that's being redirected.
 @param newChannel
        The new channel. This channel is not opened yet.
 @param flags
        Flags indicating the type of redirect. A bitmask consisting
        of flags from above.
        One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be
        set.

 @throw <any> Throwing an exception will cancel the load. No network
 request for the new channel will be made.

void onChannelRedirect(in nsIChannel oldChannel, in nsIChannel newChannel, in unsigned long flags)

 Called to resolve the charset that should be used for parsing the
 document being loaded from aChannel.

 If the charset cannot be resolved, but the implementation of
 nsICharsetResolver wants to be notified of the final resolved charset
 when one is available, it can set wantCharset to true.  If this is done,
 the caller of requestCharset is responsible for calling
 notifyResovedCharset and passing it the final resolved charset and the
 closure that requestCharset set.
 
 @param aWebNavigation the nsIWebNavigation the document is being loaded
                       in.  May be null.
 @param aChannel the channel the document is coming in from.
 @param aWantCharset gets set to true if notifyResolvedCharset should be
                     called with the given closure object.
 @param aClosure a resulting object which should be passed
                 to notifyResolvedCharset if wantCharset is set to
                 true.
 @returns the resolved charset, or the empty string if no
          charset could be determined.

ACString requestCharset(in nsIWebNavigation aWebNavigation, in nsIChannel aChannel, out boolean aWantCharset, out nsISupports aClosure)

 canAccess

 this method is called to test whether or not the given URI/channel may
 access the cookie database, either to set or get cookies.

 @param aURI
        the URI trying to access cookies
 @param aChannel
        the channel corresponding to aURI

 @return one of the following nsCookieAccess values:
         ACCESS_DEFAULT, ACCESS_ALLOW, or ACCESS_DENY

nsCookieAccess canAccess(in nsIURI aURI, in nsIChannel aChannel)

 canSetCookie

 this method is called to test whether or not the given URI/channel may
 set a specific cookie.  this method is always preceded by a call to
 canAccess. it may modify the isSession and expiry attributes of the
 cookie via the aIsSession and aExpiry parameters, in order to limit
 or extend the lifetime of the cookie. this is useful, for instance, to
 downgrade a cookie to session-only if it fails to meet certain criteria.

 @param aURI
        the URI trying to set the cookie
 @param aChannel
        the channel corresponding to aURI
 @param aCookie
        the cookie being added to the cookie database
 @param aIsSession
        when canSetCookie is invoked, this is the current isSession attribute
        of the cookie. canSetCookie may leave this value unchanged to
        preserve this attribute of the cookie.
 @param aExpiry
        when canSetCookie is invoked, this is the current expiry time of
        the cookie. canSetCookie may leave this value unchanged to
        preserve this attribute of the cookie.

 @return true if the cookie can be set.

boolean canSetCookie(in nsIURI aURI, in nsIChannel aChannel, in nsICookie2 aCookie, inout boolean aIsSession, inout PRInt64 aExpiry)

 getOriginatingURI

 determines the originating URI for a load given a channel, for third-party
 cookie blocking. this is done by leveraging the loadgroup of the channel to
 find the root content docshell, and the URI associated with its principal.
 if the root content docshell or its principal's URI cannot be obtained,
 this method will throw.

 @param aChannel
        the channel for the load trying to get or set cookies

 @return the originating URI.

nsIURI getOriginatingURI(in nsIChannel aChannel)

 Notifies the history system that the page loading via aOldChannel
 redirected to aNewChannel. Implementations should generally add the URI for
 aOldChannel to history for link coloring, but are advised not to expose it
 in the history user interface. This function is preferred if
 nsIGlobalHistory3 is available. Otherwise, nsIGlobalHistory2.addURI should
 be called with redirect=true.

 This function is preferred to nsIGlobalHistory2.addURI because it provides
 more information (including the redirect destination, channels involved,
 and redirect flags) to the history implementation.

 For implementors of nsIGlobalHistory3: The history implementation is
 responsible for sending NS_LINK_VISITED_EVENT_TOPIC to observers for
 redirect pages. This notification must be sent for history consumers for
 all non-redirect pages.

 @param aToplevel whether the URI is loaded in a top-level window.  If
        false, the load is in a subframe.

 The other params to this function are the same as those for
 nsIChannelEventSink::OnChannelRedirect.

 Note: Implementors who wish to implement this interface but rely on
 nsIGlobalHistory2.addURI for redirect processing may throw
 NS_ERROR_NOT_IMPLEMENTED from this method.  If they do so, then callers
 must call nsIGlobalHistory2.addURI upon getting the
 NS_ERROR_NOT_IMPLEMENTED result.

void addDocumentRedirect(in nsIChannel aOldChannel, in nsIChannel aNewChannel, in PRInt32 aFlags, in boolean aTopLevel)

 Notifies the history system that the page loading via aOldChannel
 redirected to aNewChannel. Implementations should generally add the URI for
 aOldChannel to history for link coloring, but are advised not to expose it
 in the history user interface. This function is preferred if
 nsIGlobalHistory3 is available. Otherwise, nsIGlobalHistory2.addURI should
 be called with redirect=true.

 This function is preferred to nsIGlobalHistory2.addURI because it provides
 more information (including the redirect destination, channels involved,
 and redirect flags) to the history implementation.

 For implementors of nsIGlobalHistory3: The history implementation is
 responsible for sending NS_LINK_VISITED_EVENT_TOPIC to observers for
 redirect pages. This notification must be sent for history consumers for
 all non-redirect pages.

 @param aToplevel whether the URI is loaded in a top-level window.  If
        false, the load is in a subframe.

 The other params to this function are the same as those for
 nsIChannelEventSink::OnChannelRedirect.

 Note: Implementors who wish to implement this interface but rely on
 nsIGlobalHistory2.addURI for redirect processing may throw
 NS_ERROR_NOT_IMPLEMENTED from this method.  If they do so, then callers
 must call nsIGlobalHistory2.addURI upon getting the
 NS_ERROR_NOT_IMPLEMENTED result.

void addDocumentRedirect(in nsIChannel aOldChannel, in nsIChannel aNewChannel, in PRInt32 aFlags, in boolean aTopLevel)

 Called when a redirect occurs due to a HTTP response like 302.  The
 redirection may be to a non-http channel.

 @return failure cancels redirect

void onRedirect(in nsIHttpChannel httpChannel, in nsIChannel newChannel)

 loadImageWithChannel allows data from an existing channel to be
 used as the image data for this content node.

 @param aChannel the channel that will deliver the data

 @return a stream listener to pump the image data into

 @see imgILoader::loadImageWithChannel

 @throws NS_ERROR_NULL_POINTER if aChannel is null

nsIStreamListener loadImageWithChannel(in nsIChannel aChannel)

 Instantiate an embedded plugin for an existing channel. The caller is
 responsible for opening the channel. It may or may not be already opened
 when this function is called.

[noscript] nsIStreamListener instantiatePluginForChannel(in nsIChannel aChannel, in nsIPluginInstanceOwner aOwner)

 Checks the passed in channel to see if there is a refresh header, 
 if there is, will setup a timer to refresh the uri found
 in the header. If docshell is busy loading a page currently, the
 request will be queued and executed when the current page 
 finishes loading. 

 Returns the NS_REFRESHURI_HEADER_FOUND success code if a refresh
 header was found and successfully setup.

 @param aChannel The channel to be parsed. 

void setupRefreshURI(in nsIChannel aChannel)

 Get the principal for the given channel.  This will typically be the
 channel owner if there is one, and the codebase principal for the
 channel's URI otherwise.  aChannel must not be null.

nsIPrincipal getChannelPrincipal(in nsIChannel aChannel)

 Synchronously load the document from the specified channel.

 @param aChannel   The channel to load the document from.
 @param aLoaderPrincipal Principal of loading document. For security
                         checks null if no securitychecks should be done

 @returns The document loaded from the URI.

nsIDOMDocument loadDocument(in nsIChannel aChannel, in nsIPrincipal aLoaderPrincipal)

 Synchronously load an XML document from the specified
 channel. The channel must be possible to open synchronously.

 @param aChannel   The channel to load the document from.
 @param aLoaderPrincipal Principal of loading document. For security
                         checks null if no securitychecks should be done

 @returns The document loaded from the URI.

nsIDOMDocument loadLocalDocument(in nsIChannel aChannel, in nsIPrincipal aLoaderPrincipal)

 Loads data from a channel. This differs from openURI in that the channel
 may already be opened, and that it returns a stream listener into which the
 caller should pump data. The caller is responsible for opening the channel
 and pumping the channel's data into the returned stream listener.

 Note: If the channel already has a loadgroup, it will be replaced with the
 window context's load group, or null if the context doesn't have one.

 If the window context's nsIURIContentListener refuses the load immediately
 (e.g. in nsIURIContentListener::onStartURIOpen), this method will return
 NS_ERROR_WONT_HANDLE_CONTENT. At that point, the caller should probably
 cancel the channel if it's already open (this method will not cancel the
 channel).

 If flags include DONT_RETARGET, and the content listener refuses the load
 during onStartRequest (e.g. in canHandleContent/isPreferred), then the
 returned stream listener's onStartRequest method will return
 NS_ERROR_WONT_HANDLE_CONTENT.

 @param aChannel
        The channel that should be loaded. The channel may already be
        opened. It must not be closed (i.e. this must be called before the
        channel calls onStopRequest on its stream listener).
 @param aFlags
        Combination (bitwise OR) of the flags specified above. 0 indicates
        default handling.
 @param aWindowContext
        If you are running the url from a doc shell or a web shell, this is
        your window context. If you have a content listener you want to
        give first crack to, the uri loader needs to be able to get it
        from the window context. We will also be using the window context
        to get at the progress event sink interface.
        <b>Must not be null!</b>

nsIStreamListener openChannel(in nsIChannel aChannel, in unsigned long aFlags, in nsIInterfaceRequestor aWindowContext)

 OpenURI requires the following parameters.....
 @param aChannel
        The channel that should be opened. This must not be asyncOpen'd yet!
        If a loadgroup is set on the channel, it will get replaced with a
        different one.
 @param aIsContentPreferred
        Should the content be displayed in a container that prefers the
        content-type, or will any container do.
 @param aWindowContext
        If you are running the url from a doc shell or a web shell, this is
        your window context. If you have a content listener you want to
        give first crack to, the uri loader needs to be able to get it
        from the window context. We will also be using the window context
        to get at the progress event sink interface.
        <b>Must not be null!</b>

void openURI(in nsIChannel aChannel, in boolean aIsContentPreferred, in nsIInterfaceRequestor aWindowContext)

 Save a channel to a file. It must not be opened yet.
 @see saveURI

void saveChannel(in nsIChannel aChannel, in nsISupports aFile)

 Adds data from a channel to the zip file. If the operation is performed
 on the queue then the channel will be opened asynchronously, otherwise
 the channel must support being opened synchronously.

 @param aZipEntry the path of the file entry
 @param aModTime the modification time of the entry in microseconds
 @param aCompression the compression level, 0 is no compression, 9 is best
 @param aChannel the channel to get the data from
 @param aQueue adds the operation to the background queue. Will be
        performed when processQueue is called.

 @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
 @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
 @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress

void addEntryChannel(in AUTF8String aZipEntry, in PRTime aModTime, in PRInt32 aCompression, in nsIChannel aChannel, in boolean aQueue)