The Tor Browser / file comparison

comparison: uriloader/base/nsIURILoader.idl

uriloader/base/nsIURILoader.idl

branch
TOR_BUG_3246
changeset 4
fc2d59ddac77
equal deleted inserted replaced
-1:000000000000 0:7b0acf8e3b9d
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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/. */
5
6 #include "nsISupports.idl"
7
8 interface nsIURIContentListener;
9 interface nsIURI;
10 interface nsILoadGroup;
11 interface nsIProgressEventSink;
12 interface nsIChannel;
13 interface nsIRequest;
14 interface nsIStreamListener;
15 interface nsIInputStream;
16 interface nsIInterfaceRequestor;
17
18 /**
19 * The uri dispatcher is responsible for taking uri's, determining
20 * the content and routing the opened url to the correct content
21 * handler.
22 *
23 * When you encounter a url you want to open, you typically call
24 * openURI, passing it the content listener for the window the uri is
25 * originating from. The uri dispatcher opens the url to discover the
26 * content type. It then gives the content listener first crack at
27 * handling the content. If it doesn't want it, the dispatcher tries
28 * to hand it off one of the registered content listeners. This allows
29 * running applications the chance to jump in and handle the content.
30 *
31 * If that also fails, then the uri dispatcher goes to the registry
32 * looking for the preferred content handler for the content type
33 * of the uri. The content handler may create an app instance
34 * or it may hand the contents off to a platform specific plugin
35 * or helper app. Or it may hand the url off to an OS registered
36 * application.
37 */
38 [scriptable, uuid(8762c4e7-be35-4958-9b81-a05685bb516d)]
39 interface nsIURILoader : nsISupports
40 {
41 /**
42 * @name Flags for opening URIs.
43 */
44 /* @{ */
45 /**
46 * Should the content be displayed in a container that prefers the
47 * content-type, or will any container do.
48 */
49 const unsigned long IS_CONTENT_PREFERRED = 1 << 0;
50 /**
51 * If this flag is set, only the listener of the specified window context will
52 * be considered for content handling; if it refuses the load, an error will
53 * be indicated.
54 */
55 const unsigned long DONT_RETARGET = 1 << 1;
56 /* @} */
57
58 /**
59 * As applications such as messenger and the browser are instantiated,
60 * they register content listener's with the uri dispatcher corresponding
61 * to content windows within that application.
62 *
63 * Note to self: we may want to optimize things a bit more by requiring
64 * the content types the registered content listener cares about.
65 *
66 * @param aContentListener
67 * The listener to register. This listener must implement
68 * nsISupportsWeakReference.
69 *
70 * @see the nsIURILoader class description
71 */
72 void registerContentListener (in nsIURIContentListener aContentListener);
73 void unRegisterContentListener (in nsIURIContentListener aContentListener);
74
75 /**
76 * OpenURI requires the following parameters.....
77 * @param aChannel
78 * The channel that should be opened. This must not be asyncOpen'd yet!
79 * If a loadgroup is set on the channel, it will get replaced with a
80 * different one.
81 * @param aFlags
82 * Combination (bitwise OR) of the flags specified above. 0 indicates
83 * default handling.
84 * @param aWindowContext
85 * If you are running the url from a doc shell or a web shell, this is
86 * your window context. If you have a content listener you want to
87 * give first crack to, the uri loader needs to be able to get it
88 * from the window context. We will also be using the window context
89 * to get at the progress event sink interface.
90 * <b>Must not be null!</b>
91 */
92 void openURI(in nsIChannel aChannel,
93 in unsigned long aFlags,
94 in nsIInterfaceRequestor aWindowContext);
95
96 /**
97 * Loads data from a channel. This differs from openURI in that the channel
98 * may already be opened, and that it returns a stream listener into which the
99 * caller should pump data. The caller is responsible for opening the channel
100 * and pumping the channel's data into the returned stream listener.
101 *
102 * Note: If the channel already has a loadgroup, it will be replaced with the
103 * window context's load group, or null if the context doesn't have one.
104 *
105 * If the window context's nsIURIContentListener refuses the load immediately
106 * (e.g. in nsIURIContentListener::onStartURIOpen), this method will return
107 * NS_ERROR_WONT_HANDLE_CONTENT. At that point, the caller should probably
108 * cancel the channel if it's already open (this method will not cancel the
109 * channel).
110 *
111 * If flags include DONT_RETARGET, and the content listener refuses the load
112 * during onStartRequest (e.g. in canHandleContent/isPreferred), then the
113 * returned stream listener's onStartRequest method will return
114 * NS_ERROR_WONT_HANDLE_CONTENT.
115 *
116 * @param aChannel
117 * The channel that should be loaded. The channel may already be
118 * opened. It must not be closed (i.e. this must be called before the
119 * channel calls onStopRequest on its stream listener).
120 * @param aFlags
121 * Combination (bitwise OR) of the flags specified above. 0 indicates
122 * default handling.
123 * @param aWindowContext
124 * If you are running the url from a doc shell or a web shell, this is
125 * your window context. If you have a content listener you want to
126 * give first crack to, the uri loader needs to be able to get it
127 * from the window context. We will also be using the window context
128 * to get at the progress event sink interface.
129 * <b>Must not be null!</b>
130 */
131 nsIStreamListener openChannel(in nsIChannel aChannel,
132 in unsigned long aFlags,
133 in nsIInterfaceRequestor aWindowContext);
134
135 /**
136 * Stops an in progress load
137 */
138 void stop(in nsISupports aLoadCookie);
139 };
140

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial