The term JSON MIME type is used to refer to the MIME
types application/json, text/json, and any MIME
@@ -82308,9 +82307,8 @@ interface Location { // but see also registerContentHandler()).
Setting the document's address: If there is no
override URL, then any Non-document content: If, given type, the new resource is to be
- handled by displaying some sort of inline content, e.g. a native rendering of the content, an
- error message because the specified type is not supported, or an inline prompt to allow the user
- to select a registered handler for
- the given type, then display the inline content, and
- then abort these steps. In the case of a registered handler being used, the algorithm will be reinvoked
- with a new URL to handle the request. Non-document content: If, given type, the new
+ resource is to be handled by displaying some sort of inline content, e.g., a native rendering of
+ the content or an error message because the specified type is not supported, then display the inline content, and then abort these
+ steps. Otherwise, the document's type is such that the resource will not affect
browsingContext, e.g., because the resource is to be handed to an external application
@@ -91321,7 +91311,7 @@ scheduleWork(); // queues a task to do lots of work
The Document created by these steps must have its
@@ -82409,19 +82407,11 @@ interface Location { // but see also
-
- navigator attribute of the
Window interface must return an instance of the Navigator interface,
which represents the identity and state of the user agent (the client), and allows Web pages to
- register themselves as potential protocol and content handlers:
Custom scheme and content handlers: the registerProtocolHandler() and registerContentHandler() methods
+ Custom scheme handlers: the registerProtocolHandler() method
[Exposed=Window,
NoInterfaceObject]
interface NavigatorContentUtils {
- // content handler registration
void registerProtocolHandler(DOMString scheme, USVString url, DOMString title);
- void registerContentHandler(DOMString mimeType, USVString url, DOMString title);
- DOMString isProtocolHandlerRegistered(DOMString scheme, USVString url);
- DOMString isContentHandlerRegistered(DOMString mimeType, USVString url);
void unregisterProtocolHandler(DOMString scheme, USVString url);
- void unregisterContentHandler(DOMString mimeType, USVString url);
};
The NavigatorContentUtils {
allows Web sites to register themselves as possible handlers for particular schemes. For example,
an online telephone messaging service could register itself as a handler of the sms: scheme, so that if the user clicks on such a link, they are given the
- opportunity to use that Web site. Analogously, the registerContentHandler() method allows
- Web sites to register themselves as possible handlers for content in a particular MIME
- type. For example, the same online telephone messaging service could register itself as a
- handler for text/vcard files, so that if the user has no native application capable
- of handling vCards, their Web browser can instead suggest they use that site to view contact
- information stored on vCards that they open.
-
-
- window .
navigator.registerProtocolHandler(scheme, url, title)
- - window .
navigator.registerContentHandler(mimeType, url, title) -
-
-
Registers a handler for the given scheme or content type, at the given URL, with the given - title.
+Registers a handler for the given scheme, at the given URL, with the given title.
The string "
@@ -91681,17 +91656,15 @@ interface NavigatorContentUtils {%s" in the URL is used as a placeholder for where to put the URL of the content to be handled.Throws a "
-SyntaxError"DOMExceptionif the "%s" string is missing in the URL.
-
User agents may, within the constraints described in this section, do whatever they like when - the methods are called. A UA could, for instance, prompt the user and offer the user the - opportunity to add the site to a shortlist of handlers, or make the handlers their default, or - cancel the request. UAs could provide such a UI through modal UI or through a non-modal transient + the method is called. A UA could, for instance, prompt the user and offer the user the opportunity + to add the site to a shortlist of handlers, or make the handlers their default, or cancel the + request. UAs could provide such a UI through modal UI or through a non-modal transient notification interface. UAs could also simply silently collect the information, providing it only when relevant to the user.
@@ -91699,17 +91672,15 @@ interface NavigatorContentUtils { declined such registrations) so that the user is not repeatedly prompted with the same request. -The arguments to the methods have the following meanings and corresponding implementation +
The arguments to the method have the following meanings and corresponding implementation requirements. The requirements that involve throwing exceptions must be processed in the order given below, stopping at the first exception thrown. (So the exceptions for the first argument take precedence over the exceptions for the second argument.)
-
-
-
- scheme (
registerProtocolHandler()only)
+ - scheme
-
-
A scheme, such as "
mailto" or "web+auth". The scheme must be compared in an ASCII case-insensitive manner by user agents for the purposes of comparing with the scheme part of URLs that they consider against the list of @@ -91762,59 +91733,6 @@ interface NavigatorContentUtils {
- - mimeType (
registerContentHandler()only)
-
- -
-
-
A MIME type, such as
- -model/vnd.flatland.3dmlorapplication/vnd.google-earth.kml+xml. The MIME type must be - compared in an ASCII case-insensitive manner by user agents for the purposes of - comparing with MIME types of documents that they consider against the list of registered - handlers.User agents must compare the given values only to the MIME type/subtype parts of content - types, not to the complete type including parameters. Thus, if mimeType - values passed to this method include characters such as commas or whitespace, or include MIME - parameters, then the handler being registered will never be used.
- -The type is compared to the MIME type used by the user agent - after the sniffing algorithms have been applied.
- -If the
- -registerContentHandler()- method is invoked with a MIME type that is in the type blocklist or - that the user agent has deemed a privileged type, the user agent must throw a - "SecurityError"DOMException.The following MIME types are in the type - blocklist:
- --
-
-
application/x-www-form-urlencoded
- application/xhtml+xml
- application/xml
- image/gif
- image/jpeg
- image/png
- image/svg+xml
- multipart/x-mixed-replace
- text/cache-manifest
- text/css
- text/html
- text/ping
- text/plain
- text/vtt
- text/xml
- - All types that the user agent supports displaying natively in a browsing context during navigation, except for
application/rss+xmlandapplication/atom+xml
-
-
This list can be changed. If there are MIME types that ought to be added, please - send feedback.
- -
-
-
- url
-
@@ -91850,7 +91768,6 @@ interface NavigatorContentUtils {
escaped version of the absolute URL of the content in question (as defined below),
then parse the resulting URL, relative to the relevant
settings object of the
NavigatorContentUtilsobject on which theregisterContentHandler()orregisterProtocolHandler()method was invoked, and then navigate an appropriate browsing context to the resulting URL. @@ -91865,21 +91782,19 @@ interface NavigatorContentUtils {If the user had visited a site at
-https://example.com/that made the following call:navigator.registerContentHandler('application/x-soup', 'soup?url=%s', 'SoupWeb™')+navigator.registerProtocolHandler('web+soup', 'soup?url=%s', 'SoupWeb™')...and then, much later, while visiting
-https://www.example.net/, clicked on a link such as:<a href="chickenkïwi.soup">Download our Chicken Kïwi soup!</a>
+<a href="web+soup:chicken-kïwi">Download our Chicken Kïwi soup!</a>
-...then, assuming this
+chickenkïwi.soupfile was served with the - MIME typeapplication/x-soup, the UA might navigate to the - following URL:...then the UA might navigate to the following URL:
-https://example.com/soup?url=https://www.example.net/chickenk%C3%AFwi.soup
+https://example.com/soup?url=web+soup:chicken-k%C3%AFwi
-This site could then fetch the
+chickenkïwi.soupfile and do - whatever it is that it does with soup (synthesize it and ship it to the user, or whatever).This site could then do whatever it is that it does with soup (synthesize it and ship it to + the user, or whatever).
This section does not define how the pages registered by these methods are used, beyond the +
This section does not define how the pages registered by this method are used, beyond the requirements on how to process the url value (see above). To some extent, the processing model for navigating across documents defines some cases where these methods are relevant, but in general UAs may use this information wherever they would otherwise consider handing content to native plugins or helper applications.
-UAs must not use registered content handlers to handle content that was returned as part of a - non-GET transaction (or rather, as part of any non-idempotent transaction), as the remote site - would not be able to fetch the same data.
--
In addition to the registration methods, there are also methods for determining if particular - handlers have been registered, and for unregistering handlers.
+In addition to the registration method, there is also a method for unregistering handlers.
-
-
- state = window .
navigator.isProtocolHandlerRegistered(scheme, url)
- - state = window .
navigator.isContentHandlerRegistered(mimeType, url)
-
- -
-
-
Returns one of the following strings describing the state of the handler given by the - arguments:
- --
-
-
new- -- Indicates that no attempt has been made to register the given handler (or that the handler - has been unregistered). It would be appropriate to promote the availability of the handler or - to just automatically register the handler. - -
registered- -- Indicates that the given handler has been registered or that the site is blocked from - registering the handler. Trying to register the handler again would have no effect. - -
declined- -- Indicates that the given handler has been offered but was rejected. Trying to register the - handler again may prompt the user again. - -
-
- window .
navigator.unregisterProtocolHandler(scheme, url)
- - window .
navigator.unregisterContentHandler(mimeType, url) -
@@ -91958,99 +91837,6 @@ interface NavigatorContentUtils {
-@@ -92124,17 +91891,17 @@ interface NavigatorContentUtils { used.
The
- -isProtocolHandlerRegistered()- method must return the handler state string that most closely describes the current - state of the handler described by the two arguments to the method, where the first argument gives - the scheme and the second gives the string used to build the URL of the page that - will handle the requests. - -The first argument must be compared to the schemes for which custom protocol handlers are - registered in an ASCII case-insensitive manner to find the relevant handlers.
- -The second argument must be preprocessed as described below, and if that is successful, must - then be matched against the proto-URLs of the relevant handlers to - find the described handler.
- -
- -The
- -isContentHandlerRegistered()- method must return the handler state string that most closely describes the current - state of the handler described by the two arguments to the method, where the first argument gives - the MIME type and the second gives the string used to build the URL of - the page that will handle the requests. - -The first argument must be compared to the MIME types for which - custom content handlers are registered in an ASCII case-insensitive manner to find - the relevant handlers.
- -The second argument must be preprocessed as described below, and if that is successful, must - then be matched against the proto-URLs of the relevant handlers to - find the described handler.
- -
- -The handler state strings are the following strings. - Each string describes several situations, as given by the following list.
- --
-
-
new- -- The described handler has never been registered for the given scheme or type.
-
-
- The described handler was once registered for the given scheme or type, but the site has - since unregistered it. If the handler were to be reregistered, the user would be notified - accordingly. - -
- The described handler was once registered for the given scheme or type, but the site has - since unregistered it, but the user has indicated that the site is to be blocked from registering - the type again, so the user agent would ignore further registration attempts. - - -
- The described handler was once registered for the given scheme or type, but the site has - since unregistered it. If the handler were to be reregistered, the user would be notified - accordingly. - -
registered- -- An attempt was made to register the described handler for the given scheme or type, but the
- user has not yet been notified, and the user agent would ignore further registration attempts.
- (Maybe the user agent batches registration requests to display them when the user requests to be
- notified about them, and the user has not yet requested that the user agent notify it of the
- previous registration attempt.)
-
-
- The described handler is registered for the given scheme or type (maybe, or maybe not, as the - default handler). - -
- The described handler is permanently blocked from being (re)registered. (Maybe the user - marked the registration attempt as spam, or blocked the site for other reasons.) - - -
- The described handler is registered for the given scheme or type (maybe, or maybe not, as the - default handler). - -
declined- -- An attempt was made to register the described handler for the given scheme or type, but the
- user has not yet been notified; however, the user might be notified if another registration
- attempt were to be made. (Maybe the last registration attempt was made while the page was in the
- background and the user closed the page without looking at it, and the user agent requires
- confirmation for this registration attempt.)
-
-
- An attempt was made to register the described handler for the given scheme or type, but the - user has not yet responded. - -
- An attempt was made to register the described handler for the given scheme or type, but the - user declined the offer. The user has not indicated that the handler is to be permanently - blocked, however, so another attempt to register the described handler might result in the user - being prompted again. - -
- The described handler was once registered for the given scheme or type, but the user has - since removed it. The user has not indicated that the handler is to be permanently blocked, - however, so another attempt to register the described handler might result in the user being - prompted again. - -
- An attempt was made to register the described handler for the given scheme or type, but the - user has not yet responded. - -
-The
-unregisterProtocolHandler()method must unregister the handler described by the two arguments to the method, where the first argument gives the scheme and the second gives the string used to build the URL of @@ -92063,27 +91849,9 @@ interface NavigatorContentUtils { then be matched against the proto-URLs of the relevant handlers to find the described handler.
- -The
- -unregisterContentHandler()- method must unregister the handler described by the two arguments to the method, where the first - argument gives the MIME type and the second gives the string used to build the - URL of the page that will handle the requests.The first argument must be compared to the MIME types for which - custom content handlers are registered in an ASCII case-insensitive manner to find - the relevant handlers.
- -The second argument must be preprocessed as described below, and if that is successful, must - then be matched against the proto-URLs of the relevant handlers to - find the described handler.
- -
- -The second argument of the four methods described above must be preprocessed as follows:
+The second argument must be preprocessed as follows:
-
-
If the string does not contain the substring "
%s", abort these steps. There's no matching handler.
@@ -92099,7 +91867,6 @@ interface NavigatorContentUtils {
Return the resulting URL string as the result of preprocessing the argument.
-
Registration spamming. User agents should consider the possibility that a site - will attempt to register a large number of handlers, possibly from multiple domains (e.g. by + will attempt to register a large number of handlers, possibly from multiple domains (e.g., by redirecting through a series of pages each on a different domain, and each registering a handler - for
+ forvideo/mpeg— analogous practices abusing other Web browser features have - been used by pornography Web sites for many years). User agents should gracefully handle such - hostile attempts, protecting the user.web+spam:— analogous practices abusing other web browser + features have been used by pornography Web sites for many years). User agents should gracefully + handle such hostile attempts, protecting the user.Misleading titles. User agents should not rely wholly on the title argument to the methods when presenting the registered handlers to the user, since sites could easily lie. For example, a site
+ registering the "Cuddly Bear Happy Scheme Handler". User agents should therefore use the handler's + origin in any UI along with any title.hostile.example.netcould claim that it was - registering the "Cuddly Bear Happy Content Handler". User agents should therefore use the - handler's domain in any UI along with any title.Hostile handler metadata. User agents should protect against typical attacks against strings embedded in their interface, for example ensuring that markup or escape characters @@ -92146,11 +91913,10 @@ interface NavigatorContentUtils {
-
-
- The user registers a third-party content handler as the default handler for a content - type. +
- The user registers a third-party scheme handler as the default handler for a scheme. -
- The user then browses their corporate Intranet site and accesses a document that uses that - content type. +
- The user then browses their corporate Intranet site and accesses a URL that uses that + scheme.
- The user agent contacts the third party and hands the third party the URL to the Intranet content. @@ -92164,11 +91930,6 @@ interface NavigatorContentUtils { Implementors might wish to consider allowing administrators to disable this feature for certain subdomains, content types, or schemes. -
- Ian Hickson <ian@hixie.ch>
- References:
- - Custom scheme and content handlers, HTML Living Standard: + Custom scheme handlers, HTML Living Standard: https://html.spec.whatwg.org/#custom-handlers
Leaking secure URLs. User agents should not send HTTPS URLs to third-party - sites registered as content handlers without the user's informed consent, for the same reason that - user agents sometimes avoid sending `
-Referer` (sic) HTTP - headers from secure sites to third-party sites.Leaking credentials. User agents must never send username or password information in the URLs that are escaped and included sent to the handler sites. User agents may even avoid attempting to pass to Web-based handlers the URLs of resources that are known to @@ -92182,54 +91943,6 @@ interface NavigatorContentUtils { button and a "deny" button, with the "accept" binding containing the name of the handler, it's important that a long name not cause the "deny" button to be pushed off the screen.
-Fingerprinting users. Since a site can detect if it has attempted to register - a particular handler or not, whether or not the user responds, the mechanism can be used to store - data. User agents are therefore strongly urged to treat registrations in the same manner as - cookies: clearing cookies for a site should also clear all registrations for that site, and - disabling cookies for a site should also disable registrations.
- - - - - -- -@@ -115306,7 +115019,7 @@ interface External {Sample user interface
- - - -A simple implementation of this feature for a desktop Web browser might work as follows.
- -The
- -registerContentHandler()method - could display a modal dialog box:
- -
In this dialog box, "Kittens at work" is the title of the page that invoked the method, - "http://kittens.example.org/" is the URL of that page, "application/x-meowmeow" is the string that - was passed to the
- -registerContentHandler()method as its first - argument (mimeType), "http://kittens.example.org/?show=%s" was the second - argument (url), and "Kittens-at-work displayer" was the third argument (title).If the user clicks the Cancel button, then nothing further happens. If the user clicks the - "Trust" button, then the handler is remembered.
- -When the user then attempts to fetch a URL that uses the "application/x-meowmeow" MIME - type, then it might display a dialog as follows:
- -
- -
In this dialog, the third option is the one that was primed by the site registering itself - earlier.
- -If the user does select that option, then the browser, in accordance with the requirements - described in the previous two sections, will redirect the user to - "http://kittens.example.org/?show=data%3Aapplication/x-meowmeow;base64,S2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%253D".
- -The
-registerProtocolHandler()method - would work equivalently, but for schemes instead of unknown content types.