michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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 nsIURIContentListener;
michael@0: interface nsIURI;
michael@0: interface nsILoadGroup;
michael@0: interface nsIProgressEventSink;
michael@0: interface nsIChannel;
michael@0: interface nsIRequest;
michael@0: interface nsIStreamListener;
michael@0: interface nsIInputStream;
michael@0: interface nsIInterfaceRequestor;
michael@0: 
michael@0: /**
michael@0:  * The uri dispatcher is responsible for taking uri's, determining
michael@0:  * the content and routing the opened url to the correct content 
michael@0:  * handler. 
michael@0:  *
michael@0:  * When you encounter a url you want to open, you typically call 
michael@0:  * openURI, passing it the content listener for the window the uri is 
michael@0:  * originating from. The uri dispatcher opens the url to discover the 
michael@0:  * content type. It then gives the content listener first crack at 
michael@0:  * handling the content. If it doesn't want it, the dispatcher tries
michael@0:  * to hand it off one of the registered content listeners. This allows
michael@0:  * running applications the chance to jump in and handle the content.
michael@0:  *
michael@0:  * If that also fails, then the uri dispatcher goes to the registry
michael@0:  * looking for the preferred content handler for the content type
michael@0:  * of the uri. The content handler may create an app instance
michael@0:  * or it may hand the contents off to a platform specific plugin
michael@0:  * or helper app. Or it may hand the url off to an OS registered 
michael@0:  * application. 
michael@0:  */
michael@0: [scriptable, uuid(8762c4e7-be35-4958-9b81-a05685bb516d)]
michael@0: interface nsIURILoader : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * @name Flags for opening URIs.
michael@0:    */
michael@0:   /* @{ */
michael@0:   /**
michael@0:    * Should the content be displayed in a container that prefers the
michael@0:    * content-type, or will any container do.
michael@0:    */
michael@0:   const unsigned long IS_CONTENT_PREFERRED = 1 << 0;
michael@0:   /**
michael@0:    * If this flag is set, only the listener of the specified window context will
michael@0:    * be considered for content handling; if it refuses the load, an error will
michael@0:    * be indicated.
michael@0:    */
michael@0:   const unsigned long DONT_RETARGET        = 1 << 1;
michael@0:   /* @} */
michael@0: 
michael@0:   /**
michael@0:    * As applications such as messenger and the browser are instantiated,
michael@0:    * they register content listener's with the uri dispatcher corresponding
michael@0:    * to content windows within that application. 
michael@0:    *
michael@0:    * Note to self: we may want to optimize things a bit more by requiring
michael@0:    * the content types the registered content listener cares about.
michael@0:    *
michael@0:    * @param aContentListener
michael@0:    *        The listener to register. This listener must implement
michael@0:    *        nsISupportsWeakReference.
michael@0:    *
michael@0:    * @see the nsIURILoader class description
michael@0:    */
michael@0:   void registerContentListener   (in nsIURIContentListener aContentListener);
michael@0:   void unRegisterContentListener (in nsIURIContentListener aContentListener);
michael@0: 
michael@0:   /**
michael@0:    * OpenURI requires the following parameters.....
michael@0:    * @param aChannel
michael@0:    *        The channel that should be opened. This must not be asyncOpen'd yet!
michael@0:    *        If a loadgroup is set on the channel, it will get replaced with a
michael@0:    *        different one.
michael@0:    * @param aFlags
michael@0:    *        Combination (bitwise OR) of the flags specified above. 0 indicates
michael@0:    *        default handling.
michael@0:    * @param aWindowContext
michael@0:    *        If you are running the url from a doc shell or a web shell, this is
michael@0:    *        your window context. If you have a content listener you want to
michael@0:    *        give first crack to, the uri loader needs to be able to get it
michael@0:    *        from the window context. We will also be using the window context
michael@0:    *        to get at the progress event sink interface.
michael@0:    *        <b>Must not be null!</b>
michael@0:    */ 
michael@0:   void openURI(in nsIChannel aChannel,
michael@0:                in unsigned long aFlags,
michael@0:                in nsIInterfaceRequestor aWindowContext);
michael@0: 
michael@0:   /**
michael@0:    * Loads data from a channel. This differs from openURI in that the channel
michael@0:    * may already be opened, and that it returns a stream listener into which the
michael@0:    * caller should pump data. The caller is responsible for opening the channel
michael@0:    * and pumping the channel's data into the returned stream listener.
michael@0:    *
michael@0:    * Note: If the channel already has a loadgroup, it will be replaced with the
michael@0:    * window context's load group, or null if the context doesn't have one.
michael@0:    *
michael@0:    * If the window context's nsIURIContentListener refuses the load immediately
michael@0:    * (e.g. in nsIURIContentListener::onStartURIOpen), this method will return
michael@0:    * NS_ERROR_WONT_HANDLE_CONTENT. At that point, the caller should probably
michael@0:    * cancel the channel if it's already open (this method will not cancel the
michael@0:    * channel).
michael@0:    *
michael@0:    * If flags include DONT_RETARGET, and the content listener refuses the load
michael@0:    * during onStartRequest (e.g. in canHandleContent/isPreferred), then the
michael@0:    * returned stream listener's onStartRequest method will return
michael@0:    * NS_ERROR_WONT_HANDLE_CONTENT.
michael@0:    *
michael@0:    * @param aChannel
michael@0:    *        The channel that should be loaded. The channel may already be
michael@0:    *        opened. It must not be closed (i.e. this must be called before the
michael@0:    *        channel calls onStopRequest on its stream listener).
michael@0:    * @param aFlags
michael@0:    *        Combination (bitwise OR) of the flags specified above. 0 indicates
michael@0:    *        default handling.
michael@0:    * @param aWindowContext
michael@0:    *        If you are running the url from a doc shell or a web shell, this is
michael@0:    *        your window context. If you have a content listener you want to
michael@0:    *        give first crack to, the uri loader needs to be able to get it
michael@0:    *        from the window context. We will also be using the window context
michael@0:    *        to get at the progress event sink interface.
michael@0:    *        <b>Must not be null!</b>
michael@0:    */ 
michael@0:   nsIStreamListener openChannel(in nsIChannel aChannel,
michael@0:                                 in unsigned long aFlags,
michael@0:                                 in nsIInterfaceRequestor aWindowContext);
michael@0: 
michael@0:   /**
michael@0:    * Stops an in progress load
michael@0:    */
michael@0:   void stop(in nsISupports aLoadCookie);
michael@0: };
michael@0: