uriloader/exthandler/nsIExternalProtocolService.idl

   1 /* -*- Mode: C++; tab-width: 3; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsIURI;
  10 interface nsIFile;
  11 interface nsIInterfaceRequestor;
  12 interface nsIHandlerInfo;
  13
  14 /**
  15  * The external protocol service is used for finding and launching
  16  * web handlers (a la registerProtocolHandler in the HTML5 draft) or
  17  * platform-specific applications for handling particular protocols.
  18  *
  19  * You can ask the external protocol service if it has an external
  20  * handler for a given protocol scheme. And you can ask it to load
  21  * the url using the default handler.
  22  */
  23 [scriptable, uuid(70f93b7a-3ec6-4bcb-b093-92d9984c9f83)]
  24 interface nsIExternalProtocolService : nsISupports
  25 {
  26   /**
  27    * Check whether a handler for a specific protocol exists.  Specifically,
  28    * this looks to see whether there are any known possible application handlers
  29    * in either the nsIHandlerService datastore or registered with the OS.
  30    *
  31    * @param aProtocolScheme The scheme from a url: http, ftp, mailto, etc.
  32    *
  33    * @return true if we have a handler and false otherwise.
  34    *
  35    * XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme?
  36    */
  37   boolean externalProtocolHandlerExists(in string aProtocolScheme);
  38
  39   /**
  40    * Check whether a handler for a specific protocol is "exposed" as a visible
  41    * feature of the current application.
  42    *
  43    * An exposed protocol handler is one that can be used in all contexts.  A
  44    * non-exposed protocol handler is one that can only be used internally by the
  45    * application.  For example, a non-exposed protocol would not be loaded by the
  46    * application in response to a link click or a X-remote openURL command.
  47    * Instead, it would be deferred to the system's external protocol handler.
  48    * XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme?
  49    */
  50   boolean isExposedProtocol(in string aProtocolScheme);
  51
  52   /**
  53    * Retrieve the handler for the given protocol.  If neither the application
  54    * nor the OS knows about a handler for the protocol, the object this method
  55    * returns will represent a default handler for unknown content.
  56    *
  57    * @param aProtocolScheme the scheme from a URL: http, ftp, mailto, etc.
  58    *
  59    * Note: aProtocolScheme should not include a trailing colon, which is part
  60    * of the URI syntax, not part of the scheme itself (i.e. pass "mailto" not
  61    * "mailto:").
  62    *
  63    * @return the handler, if any; otherwise a default handler
  64    */
  65   nsIHandlerInfo getProtocolHandlerInfo(in ACString aProtocolScheme);
  66
  67   /**
  68    * Given a scheme, looks up the protocol info from the OS.  This should be
  69    * overridden by each OS's implementation.
  70    *
  71    * @param aScheme The protocol scheme we are looking for.
  72    * @param aFound  Was an OS default handler for this scheme found?
  73    * @return An nsIHanderInfo for the protocol.
  74    */
  75   nsIHandlerInfo getProtocolHandlerInfoFromOS(in ACString aProtocolScheme,
  76                                               out boolean aFound);
  77
  78   /**
  79    * Set some sane defaults for a protocol handler object.
  80    *
  81    * @param aHandlerInfo      nsIHandlerInfo object, as returned by
  82    *                          getProtocolHandlerInfoFromOS
  83    * @param aOSHandlerExists  was the object above created for an extant
  84    *                          OS default handler?  This is generally the
  85    *                          value of the aFound out param from
  86    *                          getProtocolHandlerInfoFromOS.
  87    */
  88   void setProtocolHandlerDefaults(in nsIHandlerInfo aHandlerInfo,
  89                                   in boolean aOSHandlerExists);
  90
  91   /**
  92    * Used to load a url via an external protocol handler (if one exists)
  93    *
  94    * @param aURL The url to load
  95    *
  96    * @deprecated Use LoadURI instead (See Bug 389565 for removal)
  97    */
  98    [deprecated] void loadUrl(in nsIURI aURL);
  99
 100   /**
 101    * Used to load a URI via an external application. Might prompt the user for
 102    * permission to load the external application.
 103    *
 104    * @param aURI
 105    *        The URI to load
 106    *
 107    * @param aWindowContext
 108    *        The window to parent the dialog against, and, if a web handler
 109    *        is chosen, it is loaded in this window as well.  This parameter
 110    *        may be ultimately passed nsIURILoader.openURI in the case of a
 111    *        web handler, and aWindowContext is null or not present, web
 112    *        handlers will fail.  We need to do better than that; bug 394483
 113    *        filed in order to track.
 114    *
 115    * @note  Embedders that do not expose the http protocol should not currently
 116    *        use web-based protocol handlers, as handoff won't work correctly
 117    *        (bug 394479).
 118    */
 119   void loadURI(in nsIURI aURI,
 120                [optional] in nsIInterfaceRequestor aWindowContext);
 121
 122   /**
 123    * Gets a human-readable description for the application responsible for
 124    * handling a specific protocol.
 125    *
 126    * @param aScheme The scheme to look up. For example, "mms".
 127    *
 128    * @throw NS_ERROR_NOT_IMPLEMENTED
 129    *        If getting descriptions for protocol helpers is not supported
 130    * @throw NS_ERROR_NOT_AVAILABLE
 131    *        If no protocol helper exists for this scheme, or if it is not
 132    *        possible to get a description for it.
 133    */
 134   AString getApplicationDescription(in AUTF8String aScheme);
 135 };