diff options
Diffstat (limited to 'uriloader/base/nsIURIContentListener.idl')
| -rw-r--r-- | uriloader/base/nsIURIContentListener.idl | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/uriloader/base/nsIURIContentListener.idl b/uriloader/base/nsIURIContentListener.idl new file mode 100644 index 0000000000..000b878273 --- /dev/null +++ b/uriloader/base/nsIURIContentListener.idl @@ -0,0 +1,123 @@ +/* -*- 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(10a28f38-32e8-4c63-8aa1-12eaaebc369a)] +interface nsIURIContentListener : nsISupports +{ + /** + * 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>nullptr</code> if + * this content listener can't handle the content + * type; in this case, doContent should also fail + * (i.e., return failure nsresult). + * + * @return <code>true</code> if the load should + * be aborted and 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 ACString 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 <code>nullptr</code> if + * the content should be consumed directly as + * aContentType. + * + * @return <code>true</code> if this is a preferred + * content handler for aContentType; + * <code>false<code> 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 <code>nullptr</code> if + * the content should be consumed directly as + * aContentType. + * + * @return <code>true</code> if the data can be consumed. + * <code>false</code> 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; +}; |