uriloader/base/nsIURIContentListener.idl@6474c204b198
uriloader/base/nsIURIContentListener.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 interface nsIRequest;
9 interface nsIStreamListener;
10 interface nsIURI;
12 /**
13 * nsIURIContentListener is an interface used by components which
14 * want to know (and have a chance to handle) a particular content type.
15 * Typical usage scenarios will include running applications which register
16 * a nsIURIContentListener for each of its content windows with the uri
17 * dispatcher service.
18 */
19 [scriptable, uuid(94928AB3-8B63-11d3-989D-001083010E9B)]
20 interface nsIURIContentListener : nsISupports
21 {
22 /**
23 * Gives the original content listener first crack at stopping a load before
24 * it happens.
25 *
26 * @param aURI URI that is being opened.
27 *
28 * @return <code>false</code> if the load can continue;
29 * <code>true</code> if the open should be aborted.
30 */
31 boolean onStartURIOpen(in nsIURI aURI);
33 /**
34 * Notifies the content listener to hook up an nsIStreamListener capable of
35 * consuming the data stream.
36 *
37 * @param aContentType Content type of the data.
38 * @param aIsContentPreferred Indicates whether the content should be
39 * preferred by this listener.
40 * @param aRequest Request that is providing the data.
41 * @param aContentHandler nsIStreamListener that will consume the data.
42 * This should be set to <code>nullptr</code> if
43 * this content listener can't handle the content
44 * type; in this case, doContent should also fail
45 * (i.e., return failure nsresult).
46 *
47 * @return <code>true</code> if the load should
48 * be aborted and consumer wants to
49 * handle the load completely by itself. This
50 * causes the URI Loader do nothing else...
51 * <code>false</code> if the URI Loader should
52 * continue handling the load and call the
53 * returned streamlistener's methods.
54 */
55 boolean doContent(in string aContentType,
56 in boolean aIsContentPreferred,
57 in nsIRequest aRequest,
58 out nsIStreamListener aContentHandler);
60 /**
61 * When given a uri to dispatch, if the URI is specified as 'preferred
62 * content' then the uri loader tries to find a preferred content handler
63 * for the content type. The thought is that many content listeners may
64 * be able to handle the same content type if they have to. i.e. the mail
65 * content window can handle text/html just like a browser window content
66 * listener. However, if the user clicks on a link with text/html content,
67 * then the browser window should handle that content and not the mail
68 * window where the user may have clicked the link. This is the difference
69 * between isPreferred and canHandleContent.
70 *
71 * @param aContentType Content type of the data.
72 * @param aDesiredContentType Indicates that aContentType must be converted
73 * to aDesiredContentType before processing the
74 * data. This causes a stream converted to be
75 * inserted into the nsIStreamListener chain.
76 * This argument can be <code>nullptr</code> if
77 * the content should be consumed directly as
78 * aContentType.
79 *
80 * @return <code>true</code> if this is a preferred
81 * content handler for aContentType;
82 * <code>false<code> otherwise.
83 */
84 boolean isPreferred(in string aContentType, out string aDesiredContentType);
86 /**
87 * When given a uri to dispatch, if the URI is not specified as 'preferred
88 * content' then the uri loader calls canHandleContent to see if the content
89 * listener is capable of handling the content.
90 *
91 * @param aContentType Content type of the data.
92 * @param aIsContentPreferred Indicates whether the content should be
93 * preferred by this listener.
94 * @param aDesiredContentType Indicates that aContentType must be converted
95 * to aDesiredContentType before processing the
96 * data. This causes a stream converted to be
97 * inserted into the nsIStreamListener chain.
98 * This argument can be <code>nullptr</code> if
99 * the content should be consumed directly as
100 * aContentType.
101 *
102 * @return <code>true</code> if the data can be consumed.
103 * <code>false</code> otherwise.
104 *
105 * Note: I really envision canHandleContent as a method implemented
106 * by the docshell as the implementation is generic to all doc
107 * shells. The isPreferred decision is a decision made by a top level
108 * application content listener that sits at the top of the docshell
109 * hierarchy.
110 */
111 boolean canHandleContent(in string aContentType,
112 in boolean aIsContentPreferred,
113 out string aDesiredContentType);
115 /**
116 * The load context associated with a particular content listener.
117 * The URI Loader stores and accesses this value as needed.
118 */
119 attribute nsISupports loadCookie;
121 /**
122 * The parent content listener if this particular listener is part of a chain
123 * of content listeners (i.e. a docshell!)
124 *
125 * @note If this attribute is set to an object that implements
126 * nsISupportsWeakReference, the implementation should get the
127 * nsIWeakReference and hold that. Otherwise, the implementation
128 * should not refcount this interface; it should assume that a non
129 * null value is always valid. In that case, the caller is
130 * responsible for explicitly setting this value back to null if the
131 * parent content listener is destroyed.
132 */
133 attribute nsIURIContentListener parentContentListener;
134 };
