Mozilla

• About
• Developers
• Store
• Support
• Products

nsIChannel

---

This interface allows clients to construct "GET" requests for specific protocols, and manage them in a uniform way. Once a channel is created (via nsIIOService::newChannel), parameters for that request may be set by using the channel attributes, or by QI'ing to a subclass of nsIChannel for protocol-specific parameters. Then, the URI can be fetched by calling nsIChannel::open or nsIChannel::asyncOpen.

After a request has been completed, the channel is still valid for accessing protocol-specific results. For example, QI'ing to nsIHttpChannel allows response headers to be retrieved for the corresponding http transaction.

This interface is scriptable.

Methods

open

Synchronously open the channel.

Note: Implementations are not required to implement this method. Moreover, since this method may block the calling thread, it should not be called on a thread that processes UI events.

Syntax:

nsIInputStream nsIChannel::open()  

Parameters:

None.

Returns:

A blocking input stream to the channel's data.

asyncOpen

Asynchronously open this channel. Data is fed to the specified stream listener as it becomes available.

Syntax:

void nsIChannel::asyncOpen(
	in nsIStreamListener aListener, 
	in nsISupports aContext)  

Parameters:

aListener: The nsIStreamListener implementation.

aContext: An opaque parameter forwarded to aListener's methods.

nsresult:

NS_OK if successful.

Attributes and Constants

attribute nsIURI nsIChannel::originalURI

Gets and sets the original URI used to construct the channel. This is used in the case of a redirect or URI "resolution" (e.g. resolving a resource: URI to a file: URI) so that the original pre-redirect URI can still be obtained.

Note: this is distinctly different from the http Referrer (referring URI), which is typically the page that contained the original URI (accessible from nsIHttpChannel).

readonly attribute nsIURI nsIChannel::URI

Gets the URI corresponding to the channel. Its value is immutable.

attribute nsISupports nsIChannel::owner

Gets and sets the owner, corresponding to the entity that is responsible for this channel. It is used by the security manager to grant or deny privileges to mobile code loaded from this channel.

Note: this is a strong reference to the owner, so if the owner is also holding a strong reference to the channel, care must be taken to explicitly drop its reference to the channel.

attribute nsIInterfaceRequestor nsIChannel::notificationCallbacks

Gets and sets the notification callbacks for the channel. This is set by clients who wish to provide a means to receive progress, status and protocol-specific notifications. If this value is null, the channel implementation may use the notification callbacks from its load group. Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt, and nsIAuthPrompt.

readonly attribute nsISupports nsIChannel::securityInfo

Gets transport-level security information (if any) corresponding to the channel.

attribute ACString nsIChannel::contentType

Gets and sets the MIME type of the channel's content if available.

Note: the content type can often be wrongly specified (e.g., wrong file extension, wrong MIME type, wrong document type stored on a server, etc.), and the caller most likely wants to verify with the actual data.

attribute ACString nsIChannel::contentCharset

Gets and sets the character set of the channel's content if available and if applicable. This attribute only applies to textual data.

attribute long nsIChannel::contentLength

Gets and sets the length of the data associated with the channel if available. A value of -1 indicates that the content length is unknown.

const unsigned long LOAD_DOCUMENT_URI=1<<16

Channel specific load flag used (e.g., by the uriloader and docshell) to indicate whether or not the channel corresponds to the toplevel document.

const unsigned long LOAD_RETARGETED_DOCUMENT_URI=1<<17

Channel specific load flag, set if the end consumer for this load has been retargeted after discovering its content.

const unsigned long LOAD_REPLACE = 1 << 18

Channel specific load flag, set to indicate that onStopRequest may be followed by another onStartRequest/onStopRequest pair. It is used, for example, by the multipart/replace stream converter.

• Site Map
• Security Updates
• Contact Us
• Donate

Portions of this content are © 1998–2009 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

Last modified May 7, 2003 Document History