1/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
4 * You can obtain one at http://mozilla.org/MPL/2.0/.
5 *
6 * The origin of this IDL file is
7 * https://w3c.github.io/presentation-api/#interface-presentationrequest
8 */
9
10[Constructor(DOMString url),
11 Constructor(sequence<DOMString> urls),
12 Pref="dom.presentation.controller.enabled"]
13interface PresentationRequest : EventTarget {
14  /*
15   * A requesting page use start() to start a new connection, and it will be
16   * returned with the promise. UA may show a prompt box with a list of
17   * available devices and ask the user to grant permission, choose a device, or
18   * cancel the operation.
19   *
20   * The promise is resolved when the presenting page is successfully loaded and
21   * the communication channel is established, i.e., the connection state is
22   * "connected".
23   *
24   * The promise may be rejected duo to one of the following reasons:
25   * - "OperationError": Unexpected error occurs.
26   * - "NotFoundError":  No available device.
27   * - "AbortError":     User dismiss/cancel the device prompt box.
28   * - "NetworkError":   Failed to establish the control channel or data channel.
29   * - "TimeoutError":   Presenting page takes too long to load.
30   * - "SecurityError":  This operation is insecure.
31   */
32  [Throws]
33  Promise<PresentationConnection> start();
34
35  /*
36   * A requesting page can use reconnect(presentationId) to reopen a
37   * non-terminated presentation connection.
38   *
39   * The promise is resolved when a new presentation connection is created.
40   * The connection state is "connecting".
41   *
42   * The promise may be rejected duo to one of the following reasons:
43   * - "OperationError": Unexpected error occurs.
44   * - "NotFoundError":  Can not find a presentation connection with the presentationId.
45   * - "SecurityError":  This operation is insecure.
46   */
47  [Throws]
48  Promise<PresentationConnection> reconnect(DOMString presentationId);
49
50 /*
51  * UA triggers device discovery mechanism periodically and monitor device
52  * availability.
53  *
54  * The promise may be rejected duo to one of the following reasons:
55  * - "NotSupportedError": Unable to continuously monitor the availability.
56  * - "SecurityError":  This operation is insecure.
57  */
58  [Throws]
59  Promise<PresentationAvailability> getAvailability();
60
61  /*
62   * It is called when a connection associated with a PresentationRequest is created.
63   * The event is fired for all connections that are created for the controller.
64   */
65  attribute EventHandler onconnectionavailable;
66
67  /*
68   * A chrome page, or page which has presentation-device-manage permissiongs,
69   * uses startWithDevice() to start a new connection with specified device,
70   * and it will be returned with the promise. UA may show a prompt box with a
71   * list of available devices and ask the user to grant permission, choose a
72   * device, or cancel the operation.
73   *
74   * The promise is resolved when the presenting page is successfully loaded and
75   * the communication channel is established, i.e., the connection state is
76   * "connected".
77   *
78   * The promise may be rejected duo to one of the following reasons:
79   * - "OperationError": Unexpected error occurs.
80   * - "NotFoundError":  No available device.
81   * - "NetworkError":   Failed to establish the control channel or data channel.
82   * - "TimeoutError":   Presenting page takes too long to load.
83   */
84  [ChromeOnly, Throws]
85  Promise<PresentationConnection> startWithDevice(DOMString deviceId);
86};
87