michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIRequest; michael@0: interface nsIStreamListener; michael@0: interface nsIURI; michael@0: michael@0: /** michael@0: * nsIURIContentListener is an interface used by components which michael@0: * want to know (and have a chance to handle) a particular content type. michael@0: * Typical usage scenarios will include running applications which register michael@0: * a nsIURIContentListener for each of its content windows with the uri michael@0: * dispatcher service. michael@0: */ michael@0: [scriptable, uuid(94928AB3-8B63-11d3-989D-001083010E9B)] michael@0: interface nsIURIContentListener : nsISupports michael@0: { michael@0: /** michael@0: * Gives the original content listener first crack at stopping a load before michael@0: * it happens. michael@0: * michael@0: * @param aURI URI that is being opened. michael@0: * michael@0: * @return false if the load can continue; michael@0: * true if the open should be aborted. michael@0: */ michael@0: boolean onStartURIOpen(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Notifies the content listener to hook up an nsIStreamListener capable of michael@0: * consuming the data stream. michael@0: * michael@0: * @param aContentType Content type of the data. michael@0: * @param aIsContentPreferred Indicates whether the content should be michael@0: * preferred by this listener. michael@0: * @param aRequest Request that is providing the data. michael@0: * @param aContentHandler nsIStreamListener that will consume the data. michael@0: * This should be set to nullptr if michael@0: * this content listener can't handle the content michael@0: * type; in this case, doContent should also fail michael@0: * (i.e., return failure nsresult). michael@0: * michael@0: * @return true if the load should michael@0: * be aborted and consumer wants to michael@0: * handle the load completely by itself. This michael@0: * causes the URI Loader do nothing else... michael@0: * false if the URI Loader should michael@0: * continue handling the load and call the michael@0: * returned streamlistener's methods. michael@0: */ michael@0: boolean doContent(in string aContentType, michael@0: in boolean aIsContentPreferred, michael@0: in nsIRequest aRequest, michael@0: out nsIStreamListener aContentHandler); michael@0: michael@0: /** michael@0: * When given a uri to dispatch, if the URI is specified as 'preferred michael@0: * content' then the uri loader tries to find a preferred content handler michael@0: * for the content type. The thought is that many content listeners may michael@0: * be able to handle the same content type if they have to. i.e. the mail michael@0: * content window can handle text/html just like a browser window content michael@0: * listener. However, if the user clicks on a link with text/html content, michael@0: * then the browser window should handle that content and not the mail michael@0: * window where the user may have clicked the link. This is the difference michael@0: * between isPreferred and canHandleContent. michael@0: * michael@0: * @param aContentType Content type of the data. michael@0: * @param aDesiredContentType Indicates that aContentType must be converted michael@0: * to aDesiredContentType before processing the michael@0: * data. This causes a stream converted to be michael@0: * inserted into the nsIStreamListener chain. michael@0: * This argument can be nullptr if michael@0: * the content should be consumed directly as michael@0: * aContentType. michael@0: * michael@0: * @return true if this is a preferred michael@0: * content handler for aContentType; michael@0: * false otherwise. michael@0: */ michael@0: boolean isPreferred(in string aContentType, out string aDesiredContentType); michael@0: michael@0: /** michael@0: * When given a uri to dispatch, if the URI is not specified as 'preferred michael@0: * content' then the uri loader calls canHandleContent to see if the content michael@0: * listener is capable of handling the content. michael@0: * michael@0: * @param aContentType Content type of the data. michael@0: * @param aIsContentPreferred Indicates whether the content should be michael@0: * preferred by this listener. michael@0: * @param aDesiredContentType Indicates that aContentType must be converted michael@0: * to aDesiredContentType before processing the michael@0: * data. This causes a stream converted to be michael@0: * inserted into the nsIStreamListener chain. michael@0: * This argument can be nullptr if michael@0: * the content should be consumed directly as michael@0: * aContentType. michael@0: * michael@0: * @return true if the data can be consumed. michael@0: * false otherwise. michael@0: * michael@0: * Note: I really envision canHandleContent as a method implemented michael@0: * by the docshell as the implementation is generic to all doc michael@0: * shells. The isPreferred decision is a decision made by a top level michael@0: * application content listener that sits at the top of the docshell michael@0: * hierarchy. michael@0: */ michael@0: boolean canHandleContent(in string aContentType, michael@0: in boolean aIsContentPreferred, michael@0: out string aDesiredContentType); michael@0: michael@0: /** michael@0: * The load context associated with a particular content listener. michael@0: * The URI Loader stores and accesses this value as needed. michael@0: */ michael@0: attribute nsISupports loadCookie; michael@0: michael@0: /** michael@0: * The parent content listener if this particular listener is part of a chain michael@0: * of content listeners (i.e. a docshell!) michael@0: * michael@0: * @note If this attribute is set to an object that implements michael@0: * nsISupportsWeakReference, the implementation should get the michael@0: * nsIWeakReference and hold that. Otherwise, the implementation michael@0: * should not refcount this interface; it should assume that a non michael@0: * null value is always valid. In that case, the caller is michael@0: * responsible for explicitly setting this value back to null if the michael@0: * parent content listener is destroyed. michael@0: */ michael@0: attribute nsIURIContentListener parentContentListener; michael@0: }; michael@0: