michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIChannel;
michael@0: interface nsIParentChannel;
michael@0: 
michael@0: /**
michael@0:  * Used on the chrome process as a service to join channel implementation
michael@0:  * and parent IPC protocol side under a unique id.  Provides this way a generic
michael@0:  * communication while redirecting to various protocols.
michael@0:  *
michael@0:  * See also nsIChildChannel and nsIParentChannel.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid (efa36ea2-5b07-46fc-9534-a5acb8b77b72)]
michael@0: interface nsIRedirectChannelRegistrar : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Register the redirect target channel and obtain a unique ID for that
michael@0:    * channel.
michael@0:    *
michael@0:    * Primarily used in HttpChannelParentListener::AsyncOnChannelRedirect to get
michael@0:    * a channel id sent to the HttpChannelChild being redirected.
michael@0:    */
michael@0:   uint32_t registerChannel(in nsIChannel channel);
michael@0: 
michael@0:   /**
michael@0:    * First, search for the channel registered under the id.  If found return
michael@0:    * it.  Then, register under the same id the parent side of IPC protocol
michael@0:    * to let it be later grabbed back by the originator of the redirect and
michael@0:    * notifications from the real channel could be forwarded to this parent
michael@0:    * channel.
michael@0:    *
michael@0:    * Primarily used in parent side of an IPC protocol implementation
michael@0:    * in reaction to nsIChildChannel.connectParent(id) called from the child
michael@0:    * process.
michael@0:    */
michael@0:   nsIChannel linkChannels(in uint32_t id, in nsIParentChannel channel);
michael@0: 
michael@0:   /**
michael@0:    * Returns back the channel previously registered under the ID with
michael@0:    * registerChannel method.
michael@0:    *
michael@0:    * Primarilly used in chrome IPC side of protocols when attaching a redirect
michael@0:    * target channel to an existing 'real' channel implementation.
michael@0:    */
michael@0:   nsIChannel getRegisteredChannel(in uint32_t id);
michael@0: 
michael@0:   /**
michael@0:    * Returns the stream listener that shall be attached to the redirect target
michael@0:    * channel, all notification from the redirect target channel will be
michael@0:    * forwarded to this stream listener.
michael@0:    *
michael@0:    * Primarilly used in HttpChannelParentListener::OnRedirectResult callback
michael@0:    * to grab the created parent side of the channel and forward notifications
michael@0:    * to it.
michael@0:    */
michael@0:   nsIParentChannel getParentChannel(in uint32_t id);
michael@0: 
michael@0:   /**
michael@0:    * To not force all channel implementations to support weak reference
michael@0:    * consumers of this service must ensure release of registered channels them
michael@0:    * self.  This releases both the real and parent channel registered under
michael@0:    * the id.
michael@0:    *
michael@0:    * Primarilly used in HttpChannelParentListener::OnRedirectResult callback.
michael@0:    */
michael@0:   void deregisterChannels(in uint32_t id);
michael@0: };