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