netwerk/base/public/nsIChannelEventSink.idl@b8a032363ba2 (annotated)
netwerk/base/public/nsIChannelEventSink.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* vim:set ts=4 sw=4 sts=4 cin: */ |
| michael@0 | 3 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 4 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 5 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 6 | |
| michael@0 | 7 | #include "nsISupports.idl" |
| michael@0 | 8 | |
| michael@0 | 9 | interface nsIChannel; |
| michael@0 | 10 | interface nsIAsyncVerifyRedirectCallback; |
| michael@0 | 11 | |
| michael@0 | 12 | /** |
| michael@0 | 13 | * Implement this interface to receive control over various channel events. |
| michael@0 | 14 | * Channels will try to get this interface from a channel's |
| michael@0 | 15 | * notificationCallbacks or, if not available there, from the loadGroup's |
| michael@0 | 16 | * notificationCallbacks. |
| michael@0 | 17 | * |
| michael@0 | 18 | * These methods are called before onStartRequest. |
| michael@0 | 19 | */ |
| michael@0 | 20 | [scriptable, uuid(a430d870-df77-4502-9570-d46a8de33154)] |
| michael@0 | 21 | interface nsIChannelEventSink : nsISupports |
| michael@0 | 22 | { |
| michael@0 | 23 | /** |
| michael@0 | 24 | * This is a temporary redirect. New requests for this resource should |
| michael@0 | 25 | * continue to use the URI of the old channel. |
| michael@0 | 26 | * |
| michael@0 | 27 | * The new URI may be identical to the old one. |
| michael@0 | 28 | */ |
| michael@0 | 29 | const unsigned long REDIRECT_TEMPORARY = 1 << 0; |
| michael@0 | 30 | |
| michael@0 | 31 | /** |
| michael@0 | 32 | * This is a permanent redirect. New requests for this resource should use |
| michael@0 | 33 | * the URI of the new channel (This might be an HTTP 301 reponse). |
| michael@0 | 34 | * If this flag is not set, this is a temporary redirect. |
| michael@0 | 35 | * |
| michael@0 | 36 | * The new URI may be identical to the old one. |
| michael@0 | 37 | */ |
| michael@0 | 38 | const unsigned long REDIRECT_PERMANENT = 1 << 1; |
| michael@0 | 39 | |
| michael@0 | 40 | /** |
| michael@0 | 41 | * This is an internal redirect, i.e. it was not initiated by the remote |
| michael@0 | 42 | * server, but is specific to the channel implementation. |
| michael@0 | 43 | * |
| michael@0 | 44 | * The new URI may be identical to the old one. |
| michael@0 | 45 | */ |
| michael@0 | 46 | const unsigned long REDIRECT_INTERNAL = 1 << 2; |
| michael@0 | 47 | |
| michael@0 | 48 | /** |
| michael@0 | 49 | * Called when a redirect occurs. This may happen due to an HTTP 3xx status |
| michael@0 | 50 | * code. The purpose of this method is to notify the sink that a redirect |
| michael@0 | 51 | * is about to happen, but also to give the sink the right to veto the |
| michael@0 | 52 | * redirect by throwing or passing a failure-code in the callback. |
| michael@0 | 53 | * |
| michael@0 | 54 | * Note that vetoing the redirect simply means that |newChannel| will not |
| michael@0 | 55 | * be opened. It is important to understand that |oldChannel| will continue |
| michael@0 | 56 | * loading as if it received a HTTP 200, which includes notifying observers |
| michael@0 | 57 | * and possibly display or process content attached to the HTTP response. |
| michael@0 | 58 | * If the sink wants to prevent this loading it must explicitly deal with |
| michael@0 | 59 | * it, e.g. by calling |oldChannel->Cancel()| |
| michael@0 | 60 | * |
| michael@0 | 61 | * There is a certain freedom in implementing this method: |
| michael@0 | 62 | * |
| michael@0 | 63 | * If the return-value indicates success, a callback on |callback| is |
| michael@0 | 64 | * required. This callback can be done from within asyncOnChannelRedirect |
| michael@0 | 65 | * (effectively making the call synchronous) or at some point later |
| michael@0 | 66 | * (making the call asynchronous). Repeat: A callback must be done |
| michael@0 | 67 | * if this method returns successfully. |
| michael@0 | 68 | * |
| michael@0 | 69 | * If the return value indicates error (method throws an exception) |
| michael@0 | 70 | * the redirect is vetoed and no callback must be done. Repeat: No |
| michael@0 | 71 | * callback must be done if this method throws! |
| michael@0 | 72 | * |
| michael@0 | 73 | * @see nsIAsyncVerifyRedirectCallback::onRedirectVerifyCallback() |
| michael@0 | 74 | * |
| michael@0 | 75 | * @param oldChannel |
| michael@0 | 76 | * The channel that's being redirected. |
| michael@0 | 77 | * @param newChannel |
| michael@0 | 78 | * The new channel. This channel is not opened yet. |
| michael@0 | 79 | * @param flags |
| michael@0 | 80 | * Flags indicating the type of redirect. A bitmask consisting |
| michael@0 | 81 | * of flags from above. |
| michael@0 | 82 | * One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be |
| michael@0 | 83 | * set. |
| michael@0 | 84 | * @param callback |
| michael@0 | 85 | * Object to inform about the async result of this method |
| michael@0 | 86 | * |
| michael@0 | 87 | * @throw <any> Throwing an exception will cause the redirect to be |
| michael@0 | 88 | * cancelled |
| michael@0 | 89 | */ |
| michael@0 | 90 | void asyncOnChannelRedirect(in nsIChannel oldChannel, |
| michael@0 | 91 | in nsIChannel newChannel, |
| michael@0 | 92 | in unsigned long flags, |
| michael@0 | 93 | in nsIAsyncVerifyRedirectCallback callback); |
| michael@0 | 94 | }; |
