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