HTML5

The WindowTimers interface adds to the Window interface and the WorkerUtils interface (part of Web Workers).

Each object that implements the WindowTimers interface has a list of active timeouts and a list of active intervals. Each entry in these lists is identified by a number, which must be unique within its list for the lifetime of the object that implements the WindowTimers interface.

The setTimeout() method must run the following steps:

1. Let handle be a user-agent-defined integer that is greater than zero that will identify the timeout to be set by this call.

2. Add an entry to the list of active timeouts for handle.

3. Get the timed task handle in the list of active timeouts, and let task be the result.

4. Get the timeout, and let timeout be the result.

5. If the currently running task is a task that was created by the setTimeout() method, and timeout is less than 4, then increase timeout to 4.

6. Return handle, and then continue running this algorithm asynchronously.

7. If the method context is a Window object, wait until the Document associated with the method context has been fully active for a further timeout milliseconds (not necessarily consecutively).

   Otherwise, if the method context is a WorkerUtils object, wait until timeout milliseconds have passed with the worker not suspended (not necessarily consecutively).

   Otherwise, act as described in the specification that defines that the WindowTimers interface is implemented by some other object.

8. Wait until any invocations of this algorithm started before this one whose timeout is equal to or less than this one's have completed.

9. Optionally, wait a further user-agent defined length of time.

   This is intended to allow user agents to pad timeouts as needed to optimise the power usage of the device. For example, some processors have a low-power mode where the granularity of timers is reduced; on such platforms, user agents can slow timers down to fit this schedule instead of requiring the processor to use the more accurate mode with its associated higher power usage.

10. Queue the task task.

The clearTimeout() method must clear the entry identified as handle from the list of active timeouts of the WindowTimers object on which the method was invoked, where handle is the argument passed to the method, if any. (If handle does not identify an entry in the list of active timeouts of the WindowTimers object on which the method was invoked, the method does nothing.)

The setInterval() method must run the following steps:

1. Let handle be a user-agent-defined integer that is greater than zero that will identify the interval to be set by this call.

2. Add an entry to the list of active intervals for handle.

3. Get the timed task handle in the list of active intervals, and let task be the result.

4. Get the timeout, and let timeout be the result.

5. If timeout is less than 10, then increase timeout to 10.

6. Return handle, and then continue running this algorithm asynchronously.

7. Wait: If the method context is a Window object, wait until the Document associated with the method context has been fully active for a further interval milliseconds (not necessarily consecutively).

   Otherwise, if the method context is a WorkerUtils object, wait until interval milliseconds have passed with the worker not suspended (not necessarily consecutively).

   Otherwise, act as described in the specification that defines that the WindowTimers interface is implemented by some other object.

8. Optionally, wait a further user-agent defined length of time.

   This is intended to allow user agents to pad timeouts as needed to optimise the power usage of the device. For example, some processors have a low-power mode where the granularity of timers is reduced; on such platforms, user agents can slow timers down to fit this schedule instead of requiring the processor to use the more accurate mode with its associated higher power usage.

9. Queue the task task.

10. Return to the step labeled wait.

The clearInterval() method must clear the entry identified as handle from the list of active intervals of the WindowTimers object on which the method was invoked, where handle is the argument passed to the method, if any. (If handle does not identify an entry in the list of active intervals of the WindowTimers object on which the method was invoked, the method does nothing.)

The method context, when referenced by the algorithms in this section, is the object on which the method for which the algorithm is running is implemented (a Window or WorkerUtils object).

When the above methods are invoked and try to get the timed task handle in list list, they must run the following steps:

1. If the first argument to the invoked method is an object that has an internal [[Call]] method, then return a task that checks if the entry for handle in list has been cleared, and if it has not, calls the aforementioned [[Call]] method with as its arguments the third and subsequent arguments to the invoked method (if any), and with an undefined thisArg, and abort these steps. [ECMA262]

   Setting thisArg to undefined means that the function code will be executed with the this keyword bound to the WindowProxy or the WorkerGlobalScope object, as if the code was running in the global scope.

   Otherwise, continue with the remaining steps.

2. Apply the ToString() abstract operation to the first argument to the method, and let script source be the result. [ECMA262]

3. Let script language be JavaScript.

4. If the method context is a Window object, let global object be the method context, let browsing context be the browsing context with which global object is associated, let character encoding be the character encoding of the Document associated with global object (this is a reference, not a copy), and let base URL be the base URL of the Document associated with global object (this is a reference, not a copy).

   Otherwise, if the method context is a WorkerUtils object, let global object, browsing context, document, character encoding, and base URL be the script's global object, script's browsing context, script's document, script's URL character encoding, and script's base URL (respectively) of the script that the run a worker algorithm created when it created the method context.

   Otherwise, act as described in the specification that defines that the WindowTimers interface is implemented by some other object.

5. Return a task that checks if the entry for handle in list has been cleared, and if it has not, creates a script using script source as the script source, scripting language as the scripting language, global object as the global object, browsing context as the browsing context, document as the document, character encoding as the URL character encoding, and base URL as the base URL.

When the above methods are to get the timeout, they must run the following steps:

1. Let timeout be the second argument to the method, or zero if the argument was omitted.

2. Apply the ToString() abstract operation to timeout, and let timeout be the result. [ECMA262]

3. Apply the ToNumber() abstract operation to timeout, and let timeout be the result. [ECMA262]

4. If timeout is an Infinity value, a Not-a-Number (NaN) value, or negative, let timeout be zero.

5. Round timeout down to the nearest integer, and let timeout be the result.

6. Return timeout.

The task source for these tasks is the timer task source.

The alert(message) method, when invoked, must release the storage mutex and show the given message to the user. The user agent may make the method wait for the user to acknowledge the message before returning; if so, the user agent must pause while the method is waiting.

The confirm(message) method, when invoked, must release the storage mutex and show the given message to the user, and ask the user to respond with a positive or negative response. The user agent must then pause as the method waits for the user's response. If the user responds positively, the method must return true, and if the user responds negatively, the method must return false.

The prompt(message, default) method, when invoked, must release the storage mutex, show the given message to the user, and ask the user to either respond with a string value or abort. The user agent must then pause as the method waits for the user's response. The second argument is optional. If the second argument (default) is present, then the response must be defaulted to the value given by default. If the user aborts, then the method must return null; otherwise, the method must return the string that the user responded with.

The print() method, when invoked, must run the printing steps.

User agents should also run the printing steps whenever the user asks for the opportunity to obtain a physical form (e.g. printed copy), or the representation of a physical form (e.g. PDF copy), of a document.

The printing steps are as follows:

1. The user agent may display a message to the user and/or may abort these steps.

   For instance, a kiosk browser could silently ignore any invocations of the print() method.

   For instance, a browser on a mobile device could detect that there are no printers in the vicinity and display a message saying so before continuing to offer a "save to PDF" option.

2. The user agent must fire a simple event named beforeprint at the Window object of the Document that is being printed, as well as any nested browsing contexts in it.

   The beforeprint event can be used to annotate the printed copy, for instance adding the time at which the document was printed.

3. The user agent must release the storage mutex.

4. The user agent should offer the user the opportunity to obtain a physical form (or the representation of a physical form) of the document. The user agent may wait for the user to either accept or decline before returning; if so, the user agent must pause while the method is waiting. Even if the user agent doesn't wait at this point, the user agent must use the state of the relevant documents as they are at this point in the algorithm if and when it eventually creates the alternate form.

5. The user agent must fire a simple event named afterprint at the Window object of the Document that is being printed, as well as any nested browsing contexts in it.

   The afterprint event can be used to revert annotations added in the earlier event, as well as showing post-printing UI. For instance, if a page is walking the user through the steps of applying for a home loan, the script could automatically advance to the next step after having printed a form or other.

The showModalDialog(url, argument) method, when invoked, must cause the user agent to run the following steps:

1. Resolve url relative to the entry script's base URL.

   If this fails, then throw a SYNTAX_ERR exception and abort these steps.

2. Release the storage mutex.

3. If the user agent is configured such that this invocation of showModalDialog() is somehow disabled, then return the empty string and abort these steps.

   User agents are expected to disable this method in certain cases to avoid user annoyance (e.g. as part of their popup blocker feature). For instance, a user agent could require that a site be white-listed before enabling this method, or the user agent could be configured to only allow one modal dialog at a time.

4. Let the list of background browsing contexts be a list of all the browsing contexts that:

   • are part of the same unit of related browsing contexts as the browsing context of the Window object on which the showModalDialog() method was called, and that
   • have an active document whose origin is the same as the origin of the script that called the showModalDialog() method at the time the method was called,

   ...as well as any browsing contexts that are nested inside any of the browsing contexts matching those conditions.

5. Disable the user interface for all the browsing contexts in the list of background browsing contexts. This should prevent the user from navigating those browsing contexts, causing events to be sent to those browsing context, or editing any content in those browsing contexts. However, it does not prevent those browsing contexts from receiving events from sources other than the user, from running scripts, from running animations, and so forth.

6. Create a new auxiliary browsing context, with the opener browsing context being the browsing context of the Window object on which the showModalDialog() method was called. The new auxiliary browsing context has no name.

   This browsing context's Documents' Window objects all implement the WindowModal interface.

7. Let the dialog arguments of the new browsing context be set to the value of argument, or the 'undefined' value if the argument was omitted.

8. Let the dialog arguments' origin be the origin of the script that called the showModalDialog() method.

9. Navigate the new browsing context to the absolute URL that resulted from resolving url earlier, with replacement enabled, and with the browsing context of the script that invoked the method as the source browsing context.

10. Spin the event loop until the new browsing context is closed. (The user agent must allow the user to indicate that the browsing context is to be closed.)

11. Reenable the user interface for all the browsing contexts in the list of background browsing contexts.

12. Return the auxiliary browsing context's return value.

The Window objects of Documents hosted by browsing contexts created by the above algorithm must also implement the WindowModal interface.

When this happens, the members of the WindowModal interface, in JavaScript environments, appear to actually be part of the Window interface (e.g. they are on the same prototype chain as the window.alert() method).

Such browsing contexts have associated dialog arguments, which are stored along with the dialog arguments' origin. These values are set by the showModalDialog() method in the algorithm above, when the browsing context is created, based on the arguments provided to the method.

The dialogArguments IDL attribute, on getting, must check whether its browsing context's active document's origin is the same as the dialog arguments' origin. If it is, then the browsing context's dialog arguments must be returned unchanged. Otherwise, if the dialog arguments are an object, then the empty string must be returned, and if the dialog arguments are not an object, then the stringification of the dialog arguments must be returned.

These browsing contexts also have an associated return value. The return value of a browsing context must be initialized to the empty string when the browsing context is created.

The returnValue IDL attribute, on getting, must return the return value of its browsing context, and on setting, must set the return value to the given new value.

The 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:

These interfaces are defined separately so that other specifications can re-use parts of the Navigator interface.

appName

Must return either the string "Netscape" or the full name of the browser, e.g. "Mellblom Browsernator".

appVersion

Must return either the string "4.0" or a string representing the version of the browser in detail, e.g. "1.0 (VMS; en-US) Mellblomenator/9000".

platform

Must return either the empty string or a string representing the platform on which the browser is executing, e.g. "MacIntel", "Win32", "FreeBSD i386", "WebTV OS".

userAgent

Must return the string used for the value of the "User-Agent" header in HTTP requests, or the empty string if no such header is ever sent.

Any information in this API that varies from user to user can be used to profile the user. In fact, if enough such information is available, a user can actually be uniquely identified. For this reason, user agent implementors are strongly urged to include as little information in this API as possible.

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 his 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.

User agents should keep track of which sites have registered handlers (even if the user has 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 requirements:

scheme (registerProtocolHandler() only)

A scheme, such as ftp or sms. 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 registered handlers.

The scheme value, if it contains a colon (as in "ftp:"), will never match anything, since schemes don't contain colons.

This feature is not intended to be used with non-standard protocols.

mimeType (registerContentHandler() only)

A MIME type, such as model/vnd.flatland.3dml or application/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.

url

A string used to build the URL of the page that will handle the requests.

When the user agent uses this URL, it must replace the first occurrence of the exact literal string "%s" with an escaped version of the absolute URL of the content in question (as defined below), then resolve the resulting URL, relative to the base URL of the entry script at the time the registerContentHandler() or registerProtocolHandler() methods were invoked, and then navigate an appropriate browsing context to the resulting URL using the GET method (or equivalent for non-HTTP URLs).

To get the escaped version of the absolute URL of the content in question, the user agent must replace every character in that absolute URL that doesn't match the <query> production defined in RFC 3986 by the percent-encoded form of that character. [RFC3986]

If the user had visited a site at http://example.com/ that made the following call:

navigator.registerContentHandler('application/x-soup', 'soup?url=%s', 'SoupWeb™')

...and then, much later, while visiting http://www.example.net/, clicked on a link such as:

<a href="chickenkïwi.soup">Download our Chicken Kïwi soup!</a>

...then, assuming this chickenkïwi.soup file was served with the MIME type application/x-soup, the UA might navigate to the following URL:

http://example.com/soup?url=http://www.example.net/chickenk%C3%AFwi.soup

This site could then fetch the chickenkïwi.soup file and do whatever it is that it does with soup (synthesize it and ship it to the user, or whatever).

title

A descriptive title of the handler, which the UA might use to remind the user what the site in question is.

User agents should raise SECURITY_ERR exceptions if the methods are called with scheme or mimeType values that the UA deems to be "privileged". For example, a site attempting to register a handler for http URLs or text/html content in a Web browser would likely cause an exception to be raised.

User agents must raise a SYNTAX_ERR exception if the url argument passed to one of these methods does not contain the exact literal string "%s", or if resolving the url argument with the first occurrence of the string "%s" removed, relative to the entry script's base URL, is not successful.

User agents must not raise any other exceptions (other than binding-specific exceptions, such as for an incorrect number of arguments in an JavaScript implementation).

This section does not define how the pages registered by these methods 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.

6.5.2.1 Security and privacy

These mechanisms can introduce a number of concerns, in particular privacy concerns.

Hijacking all Web usage. User agents should not allow schemes that are key to its normal operation, such as http or https, to be rerouted through third-party sites. This would allow a user's activities to be trivially tracked, and would allow user information, even in secure connections, to be collected.

Hijacking defaults. It is strongly recommended that user agents do not automatically change any defaults, as this could lead the user to send data to remote hosts that the user is not expecting. New handlers registering themselves should never automatically cause those sites to be used.

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 redirecting through a series of pages each on a different domain, and each registering a handler for video/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.

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 hostile.example.net could 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 in such strings are not executed, that null bytes are properly handled, that over-long strings do not cause crashes or buffer overruns, and so forth.

Leaking Intranet URLs. The mechanism described in this section can result in secret Intranet URLs being leaked, in the following manner:

1. The user registers a third-party content handler as the default handler for a content type.
2. The user then browses his corporate Intranet site and accesses a document that uses that content type.
3. The user agent contacts the third party and hands the third party the URL to the Intranet content.

No actual confidential file data is leaked in this manner, but the URLs themselves could contain confidential information. For example, the URL could be http://www.corp.example.com/upcoming-aquisitions/the-sample-company.egf, which might tell the third party that Example Corporation is intending to merge with The Sample Company. Implementors might wish to consider allowing administrators to disable this feature for certain subdomains, content types, or schemes.

Leaking secure URLs. User agents should not send HTTPS URLs to third-party sites registered as content handlers, in the same way that user agents do not send 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 require authentication to access, as such sites would be unable to access the resources in question without prompting the user for credentials themselves (a practice that would require the user to know whether to trust the third-party handler, a decision many users are unable to make or even understand).

6.5.2.2 Sample user interface

This section is non-normative.

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.

The yieldForStorageUpdates() method, when invoked, must, if the storage mutex is owned by the event loop of the task that resulted in the method being called, release the storage mutex so that it is once again free. Otherwise, it must do nothing.