michael@0: /* -*- Mode: C++; tab-width: 3; indent-tabs-mode: nil; c-basic-offset: 2 -*- michael@0: * 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 nsIURI; michael@0: interface nsIFile; michael@0: interface nsIInterfaceRequestor; michael@0: interface nsIHandlerInfo; michael@0: michael@0: /** michael@0: * The external protocol service is used for finding and launching michael@0: * web handlers (a la registerProtocolHandler in the HTML5 draft) or michael@0: * platform-specific applications for handling particular protocols. michael@0: * michael@0: * You can ask the external protocol service if it has an external michael@0: * handler for a given protocol scheme. And you can ask it to load michael@0: * the url using the default handler. michael@0: */ michael@0: [scriptable, uuid(70f93b7a-3ec6-4bcb-b093-92d9984c9f83)] michael@0: interface nsIExternalProtocolService : nsISupports michael@0: { michael@0: /** michael@0: * Check whether a handler for a specific protocol exists. Specifically, michael@0: * this looks to see whether there are any known possible application handlers michael@0: * in either the nsIHandlerService datastore or registered with the OS. michael@0: * michael@0: * @param aProtocolScheme The scheme from a url: http, ftp, mailto, etc. michael@0: * michael@0: * @return true if we have a handler and false otherwise. michael@0: * michael@0: * XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme? michael@0: */ michael@0: boolean externalProtocolHandlerExists(in string aProtocolScheme); michael@0: michael@0: /** michael@0: * Check whether a handler for a specific protocol is "exposed" as a visible michael@0: * feature of the current application. michael@0: * michael@0: * An exposed protocol handler is one that can be used in all contexts. A michael@0: * non-exposed protocol handler is one that can only be used internally by the michael@0: * application. For example, a non-exposed protocol would not be loaded by the michael@0: * application in response to a link click or a X-remote openURL command. michael@0: * Instead, it would be deferred to the system's external protocol handler. michael@0: * XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme? michael@0: */ michael@0: boolean isExposedProtocol(in string aProtocolScheme); michael@0: michael@0: /** michael@0: * Retrieve the handler for the given protocol. If neither the application michael@0: * nor the OS knows about a handler for the protocol, the object this method michael@0: * returns will represent a default handler for unknown content. michael@0: * michael@0: * @param aProtocolScheme the scheme from a URL: http, ftp, mailto, etc. michael@0: * michael@0: * Note: aProtocolScheme should not include a trailing colon, which is part michael@0: * of the URI syntax, not part of the scheme itself (i.e. pass "mailto" not michael@0: * "mailto:"). michael@0: * michael@0: * @return the handler, if any; otherwise a default handler michael@0: */ michael@0: nsIHandlerInfo getProtocolHandlerInfo(in ACString aProtocolScheme); michael@0: michael@0: /** michael@0: * Given a scheme, looks up the protocol info from the OS. This should be michael@0: * overridden by each OS's implementation. michael@0: * michael@0: * @param aScheme The protocol scheme we are looking for. michael@0: * @param aFound Was an OS default handler for this scheme found? michael@0: * @return An nsIHanderInfo for the protocol. michael@0: */ michael@0: nsIHandlerInfo getProtocolHandlerInfoFromOS(in ACString aProtocolScheme, michael@0: out boolean aFound); michael@0: michael@0: /** michael@0: * Set some sane defaults for a protocol handler object. michael@0: * michael@0: * @param aHandlerInfo nsIHandlerInfo object, as returned by michael@0: * getProtocolHandlerInfoFromOS michael@0: * @param aOSHandlerExists was the object above created for an extant michael@0: * OS default handler? This is generally the michael@0: * value of the aFound out param from michael@0: * getProtocolHandlerInfoFromOS. michael@0: */ michael@0: void setProtocolHandlerDefaults(in nsIHandlerInfo aHandlerInfo, michael@0: in boolean aOSHandlerExists); michael@0: michael@0: /** michael@0: * Used to load a url via an external protocol handler (if one exists) michael@0: * michael@0: * @param aURL The url to load michael@0: * michael@0: * @deprecated Use LoadURI instead (See Bug 389565 for removal) michael@0: */ michael@0: [deprecated] void loadUrl(in nsIURI aURL); michael@0: michael@0: /** michael@0: * Used to load a URI via an external application. Might prompt the user for michael@0: * permission to load the external application. michael@0: * michael@0: * @param aURI michael@0: * The URI to load michael@0: * michael@0: * @param aWindowContext michael@0: * The window to parent the dialog against, and, if a web handler michael@0: * is chosen, it is loaded in this window as well. This parameter michael@0: * may be ultimately passed nsIURILoader.openURI in the case of a michael@0: * web handler, and aWindowContext is null or not present, web michael@0: * handlers will fail. We need to do better than that; bug 394483 michael@0: * filed in order to track. michael@0: * michael@0: * @note Embedders that do not expose the http protocol should not currently michael@0: * use web-based protocol handlers, as handoff won't work correctly michael@0: * (bug 394479). michael@0: */ michael@0: void loadURI(in nsIURI aURI, michael@0: [optional] in nsIInterfaceRequestor aWindowContext); michael@0: michael@0: /** michael@0: * Gets a human-readable description for the application responsible for michael@0: * handling a specific protocol. michael@0: * michael@0: * @param aScheme The scheme to look up. For example, "mms". michael@0: * michael@0: * @throw NS_ERROR_NOT_IMPLEMENTED michael@0: * If getting descriptions for protocol helpers is not supported michael@0: * @throw NS_ERROR_NOT_AVAILABLE michael@0: * If no protocol helper exists for this scheme, or if it is not michael@0: * possible to get a description for it. michael@0: */ michael@0: AString getApplicationDescription(in AUTF8String aScheme); michael@0: };