1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
15 * The Original Code is mozilla.org code.
17 * The Initial Developer of the Original Code is
18 * Netscape Communications Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 1999
20 * the Initial Developer. All Rights Reserved.
24 * Alternatively, the contents of this file may be used under the terms of
25 * either of the GNU General Public License Version 2 or later (the "GPL"),
26 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 * in which case the provisions of the GPL or the LGPL are applicable instead
28 * of those above. If you wish to allow use of your version of this file only
29 * under the terms of either the GPL or the LGPL, and not to allow others to
30 * use your version of this file under the terms of the MPL, indicate your
31 * decision by deleting the provisions above and replace them with the notice
32 * and other provisions required by the GPL or the LGPL. If you do not delete
33 * the provisions above, a recipient may use your version of this file under
34 * the terms of any one of the MPL, the GPL or the LGPL.
36 * ***** END LICENSE BLOCK ***** */
38 #include
"nsISupports.idl"
41 interface nsIStreamListener
;
45 * nsIURIContentListener is an interface used by components which
46 * want to know (and have a chance to handle) a particular content type.
47 * Typical usage scenarios will include running applications which register
48 * a nsIURIContentListener for each of its content windows with the uri
51 [scriptable
, uuid(94928AB3
-8B63
-11d3
-989D
-001083010E9B
)]
52 interface nsIURIContentListener
: nsISupports
55 * Gives the original content listener first crack at stopping a load before
58 * @param aURI URI that is being opened.
60 * @return <code>false</code> if the load can continue;
61 * <code>true</code> if the open should be aborted.
63 boolean onStartURIOpen
(in nsIURI aURI
);
66 * Notifies the content listener to hook up an nsIStreamListener capable of
67 * consuming the data stream.
69 * @param aContentType Content type of the data.
70 * @param aIsContentPreferred Indicates whether the content should be
71 * preferred by this listener.
72 * @param aRequest Request that is providing the data.
73 * @param aContentHandler nsIStreamListener that will consume the data.
74 * This should be set to <code>nsnull</code> if
75 * this content listener can't handle the content
78 * @return <code>true</code> if the consumer wants to
79 * handle the load completely by itself. This
80 * causes the URI Loader do nothing else...
81 * <code>false</code> if the URI Loader should
82 * continue handling the load and call the
83 * returned streamlistener's methods.
85 boolean doContent
(in string aContentType
,
86 in boolean aIsContentPreferred
,
87 in nsIRequest aRequest
,
88 out nsIStreamListener aContentHandler
);
91 * When given a uri to dispatch, if the URI is specified as 'preferred
92 * content' then the uri loader tries to find a preferred content handler
93 * for the content type. The thought is that many content listeners may
94 * be able to handle the same content type if they have to. i.e. the mail
95 * content window can handle text/html just like a browser window content
96 * listener. However, if the user clicks on a link with text/html content,
97 * then the browser window should handle that content and not the mail
98 * window where the user may have clicked the link. This is the difference
99 * between isPreferred and canHandleContent.
101 * @param aContentType Content type of the data.
102 * @param aDesiredContentType Indicates that aContentType must be converted
103 * to aDesiredContentType before processing the
104 * data. This causes a stream converted to be
105 * inserted into the nsIStreamListener chain.
106 * This argument can be <code>nsnull</code> if
107 * the content should be consumed directly as
110 * @return <code>true</code> if this is a preferred
111 * content handler for aContentType;
112 * <code>false<code> otherwise.
114 boolean isPreferred
(in string aContentType
, out string aDesiredContentType
);
117 * When given a uri to dispatch, if the URI is not specified as 'preferred
118 * content' then the uri loader calls canHandleContent to see if the content
119 * listener is capable of handling the content.
121 * @param aContentType Content type of the data.
122 * @param aIsContentPreferred Indicates whether the content should be
123 * preferred by this listener.
124 * @param aDesiredContentType Indicates that aContentType must be converted
125 * to aDesiredContentType before processing the
126 * data. This causes a stream converted to be
127 * inserted into the nsIStreamListener chain.
128 * This argument can be <code>nsnull</code> if
129 * the content should be consumed directly as
132 * @return <code>true</code> if the data can be consumed.
133 * <code>false</code> otherwise.
135 * Note: I really envision canHandleContent as a method implemented
136 * by the docshell as the implementation is generic to all doc
137 * shells. The isPreferred decision is a decision made by a top level
138 * application content listener that sits at the top of the docshell
141 boolean canHandleContent
(in string aContentType
,
142 in boolean aIsContentPreferred
,
143 out string aDesiredContentType
);
146 * The load context associated with a particular content listener.
147 * The URI Loader stores and accesses this value as needed.
149 attribute nsISupports loadCookie
;
152 * The parent content listener if this particular listener is part of a chain
153 * of content listeners (i.e. a docshell!)
155 * @note If this attribute is set to an object that implements
156 * nsISupportsWeakReference, the implementation should get the
157 * nsIWeakReference and hold that. Otherwise, the implementation
158 * should not refcount this interface; it should assume that a non
159 * null value is always valid. In that case, the caller is
160 * responsible for explicitly setting this value back to null if the
161 * parent content listener is destroyed.
163 attribute nsIURIContentListener parentContentListener
;