1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/uriloader/exthandler/nsIExternalProtocolService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,135 @@
1.4 +/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIURI;
1.13 +interface nsIFile;
1.14 +interface nsIInterfaceRequestor;
1.15 +interface nsIHandlerInfo;
1.16 +
1.17 +/**
1.18 + * The external protocol service is used for finding and launching
1.19 + * web handlers (a la registerProtocolHandler in the HTML5 draft) or
1.20 + * platform-specific applications for handling particular protocols.
1.21 + *
1.22 + * You can ask the external protocol service if it has an external
1.23 + * handler for a given protocol scheme. And you can ask it to load
1.24 + * the url using the default handler.
1.25 + */
1.26 +[scriptable, uuid(70f93b7a-3ec6-4bcb-b093-92d9984c9f83)]
1.27 +interface nsIExternalProtocolService : nsISupports
1.28 +{
1.29 + /**
1.30 + * Check whether a handler for a specific protocol exists. Specifically,
1.31 + * this looks to see whether there are any known possible application handlers
1.32 + * in either the nsIHandlerService datastore or registered with the OS.
1.33 + *
1.34 + * @param aProtocolScheme The scheme from a url: http, ftp, mailto, etc.
1.35 + *
1.36 + * @return true if we have a handler and false otherwise.
1.37 + *
1.38 + * XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme?
1.39 + */
1.40 + boolean externalProtocolHandlerExists(in string aProtocolScheme);
1.41 +
1.42 + /**
1.43 + * Check whether a handler for a specific protocol is "exposed" as a visible
1.44 + * feature of the current application.
1.45 + *
1.46 + * An exposed protocol handler is one that can be used in all contexts. A
1.47 + * non-exposed protocol handler is one that can only be used internally by the
1.48 + * application. For example, a non-exposed protocol would not be loaded by the
1.49 + * application in response to a link click or a X-remote openURL command.
1.50 + * Instead, it would be deferred to the system's external protocol handler.
1.51 + * XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme?
1.52 + */
1.53 + boolean isExposedProtocol(in string aProtocolScheme);
1.54 +
1.55 + /**
1.56 + * Retrieve the handler for the given protocol. If neither the application
1.57 + * nor the OS knows about a handler for the protocol, the object this method
1.58 + * returns will represent a default handler for unknown content.
1.59 + *
1.60 + * @param aProtocolScheme the scheme from a URL: http, ftp, mailto, etc.
1.61 + *
1.62 + * Note: aProtocolScheme should not include a trailing colon, which is part
1.63 + * of the URI syntax, not part of the scheme itself (i.e. pass "mailto" not
1.64 + * "mailto:").
1.65 + *
1.66 + * @return the handler, if any; otherwise a default handler
1.67 + */
1.68 + nsIHandlerInfo getProtocolHandlerInfo(in ACString aProtocolScheme);
1.69 +
1.70 + /**
1.71 + * Given a scheme, looks up the protocol info from the OS. This should be
1.72 + * overridden by each OS's implementation.
1.73 + *
1.74 + * @param aScheme The protocol scheme we are looking for.
1.75 + * @param aFound Was an OS default handler for this scheme found?
1.76 + * @return An nsIHanderInfo for the protocol.
1.77 + */
1.78 + nsIHandlerInfo getProtocolHandlerInfoFromOS(in ACString aProtocolScheme,
1.79 + out boolean aFound);
1.80 +
1.81 + /**
1.82 + * Set some sane defaults for a protocol handler object.
1.83 + *
1.84 + * @param aHandlerInfo nsIHandlerInfo object, as returned by
1.85 + * getProtocolHandlerInfoFromOS
1.86 + * @param aOSHandlerExists was the object above created for an extant
1.87 + * OS default handler? This is generally the
1.88 + * value of the aFound out param from
1.89 + * getProtocolHandlerInfoFromOS.
1.90 + */
1.91 + void setProtocolHandlerDefaults(in nsIHandlerInfo aHandlerInfo,
1.92 + in boolean aOSHandlerExists);
1.93 +
1.94 + /**
1.95 + * Used to load a url via an external protocol handler (if one exists)
1.96 + *
1.97 + * @param aURL The url to load
1.98 + *
1.99 + * @deprecated Use LoadURI instead (See Bug 389565 for removal)
1.100 + */
1.101 + [deprecated] void loadUrl(in nsIURI aURL);
1.102 +
1.103 + /**
1.104 + * Used to load a URI via an external application. Might prompt the user for
1.105 + * permission to load the external application.
1.106 + *
1.107 + * @param aURI
1.108 + * The URI to load
1.109 + *
1.110 + * @param aWindowContext
1.111 + * The window to parent the dialog against, and, if a web handler
1.112 + * is chosen, it is loaded in this window as well. This parameter
1.113 + * may be ultimately passed nsIURILoader.openURI in the case of a
1.114 + * web handler, and aWindowContext is null or not present, web
1.115 + * handlers will fail. We need to do better than that; bug 394483
1.116 + * filed in order to track.
1.117 + *
1.118 + * @note Embedders that do not expose the http protocol should not currently
1.119 + * use web-based protocol handlers, as handoff won't work correctly
1.120 + * (bug 394479).
1.121 + */
1.122 + void loadURI(in nsIURI aURI,
1.123 + [optional] in nsIInterfaceRequestor aWindowContext);
1.124 +
1.125 + /**
1.126 + * Gets a human-readable description for the application responsible for
1.127 + * handling a specific protocol.
1.128 + *
1.129 + * @param aScheme The scheme to look up. For example, "mms".
1.130 + *
1.131 + * @throw NS_ERROR_NOT_IMPLEMENTED
1.132 + * If getting descriptions for protocol helpers is not supported
1.133 + * @throw NS_ERROR_NOT_AVAILABLE
1.134 + * If no protocol helper exists for this scheme, or if it is not
1.135 + * possible to get a description for it.
1.136 + */
1.137 + AString getApplicationDescription(in AUTF8String aScheme);
1.138 +};
