1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIChannelEventSink.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,94 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* vim:set ts=4 sw=4 sts=4 cin: */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIChannel;
1.13 +interface nsIAsyncVerifyRedirectCallback;
1.14 +
1.15 +/**
1.16 + * Implement this interface to receive control over various channel events.
1.17 + * Channels will try to get this interface from a channel's
1.18 + * notificationCallbacks or, if not available there, from the loadGroup's
1.19 + * notificationCallbacks.
1.20 + *
1.21 + * These methods are called before onStartRequest.
1.22 + */
1.23 +[scriptable, uuid(a430d870-df77-4502-9570-d46a8de33154)]
1.24 +interface nsIChannelEventSink : nsISupports
1.25 +{
1.26 + /**
1.27 + * This is a temporary redirect. New requests for this resource should
1.28 + * continue to use the URI of the old channel.
1.29 + *
1.30 + * The new URI may be identical to the old one.
1.31 + */
1.32 + const unsigned long REDIRECT_TEMPORARY = 1 << 0;
1.33 +
1.34 + /**
1.35 + * This is a permanent redirect. New requests for this resource should use
1.36 + * the URI of the new channel (This might be an HTTP 301 reponse).
1.37 + * If this flag is not set, this is a temporary redirect.
1.38 + *
1.39 + * The new URI may be identical to the old one.
1.40 + */
1.41 + const unsigned long REDIRECT_PERMANENT = 1 << 1;
1.42 +
1.43 + /**
1.44 + * This is an internal redirect, i.e. it was not initiated by the remote
1.45 + * server, but is specific to the channel implementation.
1.46 + *
1.47 + * The new URI may be identical to the old one.
1.48 + */
1.49 + const unsigned long REDIRECT_INTERNAL = 1 << 2;
1.50 +
1.51 + /**
1.52 + * Called when a redirect occurs. This may happen due to an HTTP 3xx status
1.53 + * code. The purpose of this method is to notify the sink that a redirect
1.54 + * is about to happen, but also to give the sink the right to veto the
1.55 + * redirect by throwing or passing a failure-code in the callback.
1.56 + *
1.57 + * Note that vetoing the redirect simply means that |newChannel| will not
1.58 + * be opened. It is important to understand that |oldChannel| will continue
1.59 + * loading as if it received a HTTP 200, which includes notifying observers
1.60 + * and possibly display or process content attached to the HTTP response.
1.61 + * If the sink wants to prevent this loading it must explicitly deal with
1.62 + * it, e.g. by calling |oldChannel->Cancel()|
1.63 + *
1.64 + * There is a certain freedom in implementing this method:
1.65 + *
1.66 + * If the return-value indicates success, a callback on |callback| is
1.67 + * required. This callback can be done from within asyncOnChannelRedirect
1.68 + * (effectively making the call synchronous) or at some point later
1.69 + * (making the call asynchronous). Repeat: A callback must be done
1.70 + * if this method returns successfully.
1.71 + *
1.72 + * If the return value indicates error (method throws an exception)
1.73 + * the redirect is vetoed and no callback must be done. Repeat: No
1.74 + * callback must be done if this method throws!
1.75 + *
1.76 + * @see nsIAsyncVerifyRedirectCallback::onRedirectVerifyCallback()
1.77 + *
1.78 + * @param oldChannel
1.79 + * The channel that's being redirected.
1.80 + * @param newChannel
1.81 + * The new channel. This channel is not opened yet.
1.82 + * @param flags
1.83 + * Flags indicating the type of redirect. A bitmask consisting
1.84 + * of flags from above.
1.85 + * One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be
1.86 + * set.
1.87 + * @param callback
1.88 + * Object to inform about the async result of this method
1.89 + *
1.90 + * @throw <any> Throwing an exception will cause the redirect to be
1.91 + * cancelled
1.92 + */
1.93 + void asyncOnChannelRedirect(in nsIChannel oldChannel,
1.94 + in nsIChannel newChannel,
1.95 + in unsigned long flags,
1.96 + in nsIAsyncVerifyRedirectCallback callback);
1.97 +};
