netwerk/base/public/nsIChannelEventSink.idlScriptable
Implement this interface to gain control over various channel events, such as redirects.
1.0
66
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Channels will try to get this interface from a channel's notificationCallbacks or, if not available there, from the loadGroup's notificationCallbacks.

These methods are called before onStartRequest.

Note: Prior to Gecko 2.0, redirect handling was synchronous, using the onChannelRedirect() method. Starting in Gecko 2.0, that method no longer exists, and instead the asyncOnChannelRedirect() method is called; this uses a callback to handle redirects asynchronously.

Method overview

void asyncOnChannelRedirect(in nsIChannel oldChannel, in nsIChannel newChannel, in unsigned long flags, in nsIAsyncVerifyRedirectCallback callback);
void onChannelRedirect(in nsIChannel oldChannel, in nsIChannel newChannel, in unsigned long flags); Obsolete since Gecko 2.0

Constants

Constant Value Description
REDIRECT_TEMPORARY 1 << 0

This is a temporary redirect. New requests for this resource should continue to use the URI of the old channel.

The new URI may be identical to the old one.
REDIRECT_PERMANENT 1 << 1

This is a permanent redirect. New requests for this resource should use the URI of the new channel (This might be an HTTP 301 reponse). If this flag is not set, this is a temporary redirect.

The new URI may be identical to the old one.
REDIRECT_INTERNAL 1 << 2

This is an internal redirect, i.e. it was not initiated by the remote server, but is specific to the channel implementation.

The new URI may be identical to the old one.

Methods

asyncOnChannelRedirect()

Called when a redirect occurs. This may happen due to an HTTP 3xx status code. This method notifies the sink that a redirect is about to happen, but also to gives the sink the right to veto the redirect by throwing an exception or passing a failure code in the callback.

Note: Vetoing the redirect simply means that newChannel will not be opened. It is important to understand that oldChannel will continue loading as if it received a response of HTTP 200, which includes notifying observers and possibly display or process content attached to the HTTP response. If the sink wants to prevent this loading it must explicitly deal with it, e.g. by calling oldChannel->Cancel()

There is a certain freedom in implementing this method:

If the return-value indicates success, a callback on callback is required. This callback can be done from within asyncOnChannelRedirect() (effectively making the call synchronous) or at some point later (making the call asynchronous).

If the return value indicates that an error occurred, in which case an exception is thrown, the redirect is vetoed and no callback must be done.

void asyncOnChannelRedirect(
  in nsIChannel oldChannel,
  in nsIChannel newChannel,
  in unsigned long flags,
  in nsIAsyncVerifyRedirectCallback callback
);
Parameters
oldChannel
The channel that's being redirected.
newChannel
The new channel. This channel is not opened yet.
flags
Flags indicating the type of redirect. A bitmask consisting of flags from above. One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be set.
callback
Object to inform about the async result of this method.
Exceptions thrown

This method can throw any exception; if an exception occurs, the load will be canceled, and no network requests will occur for the new channel. The redirect will be canceled.

onChannelRedirect()

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Called when a redirect occurs. This may happen due to an HTTP 3xx status code.

void onChannelRedirect(
  in nsIChannel oldChannel,
  in nsIChannel newChannel,
  in unsigned long flags
);
Parameters
oldChannel
The channel that's being redirected.
newChannel
The new channel. This channel is not opened yet.
flags
Flags indicating the type of redirect. A bitmask consisting of flags from above. One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be set.

See also