diff -r 000000000000 -r 6474c204b198 uriloader/base/nsIURIContentListener.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uriloader/base/nsIURIContentListener.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,135 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" + +interface nsIRequest; +interface nsIStreamListener; +interface nsIURI; + +/** + * 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. + */ +[scriptable, uuid(94928AB3-8B63-11d3-989D-001083010E9B)] +interface nsIURIContentListener : nsISupports +{ + /** + * Gives the original content listener first crack at stopping a load before + * it happens. + * + * @param aURI URI that is being opened. + * + * @return false if the load can continue; + * true if the open should be aborted. + */ + boolean onStartURIOpen(in nsIURI aURI); + + /** + * 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 nullptr if + * this content listener can't handle the content + * type; in this case, doContent should also fail + * (i.e., return failure nsresult). + * + * @return true if the load should + * be aborted and 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. + */ + boolean doContent(in string aContentType, + in boolean aIsContentPreferred, + in nsIRequest aRequest, + out nsIStreamListener aContentHandler); + + /** + * 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. + * + * @param aContentType Content type of the data. + * @param aDesiredContentType Indicates that aContentType must be converted + * to aDesiredContentType before processing the + * data. This causes a stream converted to be + * inserted into the nsIStreamListener chain. + * This argument can be nullptr if + * the content should be consumed directly as + * aContentType. + * + * @return true if this is a preferred + * content handler for aContentType; + * false otherwise. + */ + boolean isPreferred(in string aContentType, out string aDesiredContentType); + + /** + * 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. + * + * @param aContentType Content type of the data. + * @param aIsContentPreferred Indicates whether the content should be + * preferred by this listener. + * @param aDesiredContentType Indicates that aContentType must be converted + * to aDesiredContentType before processing the + * data. This causes a stream converted to be + * inserted into the nsIStreamListener chain. + * This argument can be nullptr if + * the content should be consumed directly as + * aContentType. + * + * @return true if the data can be consumed. + * false otherwise. + * + * 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. + */ + boolean canHandleContent(in string aContentType, + in boolean aIsContentPreferred, + out string aDesiredContentType); + + /** + * The load context associated with a particular content listener. + * The URI Loader stores and accesses this value as needed. + */ + attribute nsISupports loadCookie; + + /** + * The parent content listener if this particular listener is part of a chain + * of content listeners (i.e. a docshell!) + * + * @note If this attribute is set to an object that implements + * nsISupportsWeakReference, the implementation should get the + * nsIWeakReference and hold that. Otherwise, the implementation + * should not refcount this interface; it should assume that a non + * null value is always valid. In that case, the caller is + * responsible for explicitly setting this value back to null if the + * parent content listener is destroyed. + */ + attribute nsIURIContentListener parentContentListener; +}; +