netwerk/base/nsIRedirectChannelRegistrar.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIChannel;
   8 interface nsIParentChannel;
   9
  10 /**
  11  * Used on the chrome process as a service to join channel implementation
  12  * and parent IPC protocol side under a unique id.  Provides this way a generic
  13  * communication while redirecting to various protocols.
  14  *
  15  * See also nsIChildChannel and nsIParentChannel.
  16  */
  17
  18 [scriptable, uuid (efa36ea2-5b07-46fc-9534-a5acb8b77b72)]
  19 interface nsIRedirectChannelRegistrar : nsISupports
  20 {
  21   /**
  22    * Register the redirect target channel. The passed id needs to be a
  23    * unique ID for that channel (see `nsContentUtils::GenerateLoadIdentifier`).
  24    *
  25    * Primarily used in ParentChannelListener::AsyncOnChannelRedirect to get
  26    * a channel id sent to the HttpChannelChild being redirected.
  27    */
  28   void registerChannel(in nsIChannel channel, in uint64_t id);
  29
  30   /**
  31    * First, search for the channel registered under the id.  If found return
  32    * it.  Then, register under the same id the parent side of IPC protocol
  33    * to let it be later grabbed back by the originator of the redirect and
  34    * notifications from the real channel could be forwarded to this parent
  35    * channel.
  36    *
  37    * Primarily used in parent side of an IPC protocol implementation
  38    * in reaction to nsIChildChannel.connectParent(id) called from the child
  39    * process.
  40    */
  41   nsIChannel linkChannels(in uint64_t id, in nsIParentChannel channel);
  42
  43   /**
  44    * Returns back the channel previously registered under the ID with
  45    * registerChannel method.
  46    *
  47    * Primarilly used in chrome IPC side of protocols when attaching a redirect
  48    * target channel to an existing 'real' channel implementation.
  49    */
  50   nsIChannel getRegisteredChannel(in uint64_t id);
  51
  52   /**
  53    * Returns the stream listener that shall be attached to the redirect target
  54    * channel, all notification from the redirect target channel will be
  55    * forwarded to this stream listener.
  56    *
  57    * Primarilly used in HttpChannelParent::OnRedirectResult callback to grab
  58    * the created parent side of the channel and forward notifications to it.
  59    */
  60   nsIParentChannel getParentChannel(in uint64_t id);
  61
  62   /**
  63    * To not force all channel implementations to support weak reference
  64    * consumers of this service must ensure release of registered channels them
  65    * self.  This releases both the real and parent channel registered under
  66    * the id.
  67    *
  68    * Primarilly used in HttpChannelParent::OnRedirectResult callback.
  69    */
  70   void deregisterChannels(in uint64_t id);
  71 };