WARNING: Most of this content (with the exception of the Mozilla 1.9 XPCOM reference) is very old, and can be expected to be out of date and possibly obsolete. For better XUL documentation, please visit the XUL hub at the Mozilla Developer Center.

nsIURIContentListener

IID:94928AB3-8B63-11d3-989D-001083010E9B
Inherits From:nsISupports
Status:FROZEN

nsIURIContentListener is an interface used by components which want to know (and have a chance to handle) a particular content type. Typical usage scenarios will include running applications which register a nsIURIContentListener for each of its content windows with the uri dispatcher service.

This interface is implemented by the following components:

Properties

nsISupports loadCookie

The load context associated with a particular content listener. The URI Loader stores and accesses this value as needed.

nsIURIContentListener parentContentListener

The parent content listener if this particular listener is part of a chain of content listeners (i.e. a docshell!)

Methods

PRBool canHandleContent ( char* contentType , PRBool isContentPreferred , out char* desiredContentType ) PRBool doContent ( char* contentType , PRBool isContentPreferred , nsIRequest request , out nsIStreamListener contentHandler ) PRBool isPreferred ( char* contentType , out char* desiredContentType ) PRBool onStartURIOpen ( nsIURI URI )

PRBool canHandleContent ( char* contentType , PRBool isContentPreferred , out char* desiredContentType )

When given a uri to dispatch, if the URI is not specified as 'preferred content' then the uri loader calls canHandleContent to see if the content listener is capable of handling the content.

Note: I really envision canHandleContent as a method implemented by the docshell as the implementation is generic to all doc shells. The isPreferred decision is a decision made by a top level application content listener that sits at the top of the docshell hierarchy.

Arguments:
contentType: Content type of the data.
isContentPreferred: Indicates whether the content should be preferred by this listener.
desiredContentType: Indicates that contentType must be converted to desiredContentType before processing the data. This causes a stream converted to be inserted into the nsIStreamListener chain. This argument can be nsnull if the content should be consumed directly as contentType.
Returns:
true if the data can be consumed. false otherwise.

PRBool doContent ( char* contentType , PRBool isContentPreferred , nsIRequest request , out nsIStreamListener contentHandler )

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

Arguments:
contentType: Content type of the data.
isContentPreferred: Indicates whether the content should be preferred by this listener.
request: Request that is providing the data.
contentHandler: nsIStreamListener that will consume the data. This should be set to nsnull if this content listener can't handle the content type.
Returns:
true if the consumer wants to handle the load completely by itself. This causes the URI Loader do nothing else... false if the URI Loader should continue handling the load and call the returned streamlistener's methods.

PRBool isPreferred ( char* contentType , out char* desiredContentType )

When given a uri to dispatch, if the URI is specified as 'preferred content' then the uri loader tries to find a preferred content handler for the content type. The thought is that many content listeners may be able to handle the same content type if they have to. i.e. the mail content window can handle text/html just like a browser window content listener. However, if the user clicks on a link with text/html content, then the browser window should handle that content and not the mail window where the user may have clicked the link. This is the difference between isPreferred and canHandleContent.

Arguments:
contentType: Content type of the data.
desiredContentType: Indicates that contentType must be converted to desiredContentType before processing the data. This causes a stream converted to be inserted into the nsIStreamListener chain. This argument can be nsnull if the content should be consumed directly as contentType.
Returns:
true if this is a preferred content handler for aContentType; false otherwise.

PRBool onStartURIOpen ( nsIURI URI )

Gives the original content listener first crack at stopping a load before it happens.

Arguments:
URI: URI that is being opened.
Returns:
false if the load can continue; true if the open should be aborted.

References

This interface is the type of the following properties:

nsIURIContentListener.parentContentListener, nsIWebBrowser.parentURIContentListener

This interface is passed as an argument to the following methods:

nsIURILoader.registerContentListener, nsIURILoader.unRegisterContentListener

Reference documentation is generated from Mozilla's source.

Copyright © 1999-2006 XULPlanet.com