1// Copyright 2015 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// Use the <code>chrome.bluetoothPrivate</code> API to control the Bluetooth
6// adapter state and handle device pairing.
7// NOTE: This IDL is dependent on bluetooth.idl.
8
9[implemented_in = "extensions/browser/api/bluetooth/bluetooth_private_api.h"]
10namespace bluetoothPrivate {
11  // Events that can occur during pairing. The method used for pairing varies
12  // depending on the capability of the two devices.
13  enum PairingEventType {
14    // An alphanumeric PIN code is required to be entered by the user.
15    requestPincode,
16
17    // Display a PIN code to the user.
18    displayPincode,
19
20    // A numeric passkey is required to be entered by the user.
21    requestPasskey,
22
23    // Display a zero padded 6 digit numeric passkey that the user entered on
24    // the remote device. This event may occur multiple times during pairing to
25    // update the entered passkey.
26    displayPasskey,
27
28    // The number of keys inputted by the user on the remote device when
29    // entering a passkey. This event may be called multiple times during
30    // pairing to update the number of keys inputted.
31    keysEntered,
32
33    // Requests that a 6 digit passkey be displayed and the user confirms that
34    // both devies show the same passkey.
35    confirmPasskey,
36
37    // Requests authorization for a pairing under the just-works model. It is up
38    // to the app to ask for user confirmation.
39    requestAuthorization,
40
41    // Pairing is completed.
42    complete
43  };
44
45  // Results for connect(). See function declaration for details.
46  enum ConnectResultType {
47    alreadyConnected,
48    authCanceled,
49    authFailed,
50    authRejected,
51    authTimeout,
52    failed,
53    inProgress,
54    success,
55    unknownError,
56    unsupportedDevice
57  };
58
59  // Valid pairing responses.
60  enum PairingResponse {
61    confirm, reject, cancel
62  };
63
64  enum TransportType {
65    le, bredr, dual
66  };
67
68  // A pairing event received from a Bluetooth device.
69  dictionary PairingEvent {
70    PairingEventType pairing;
71    bluetooth.Device device;
72    DOMString? pincode;
73    long? passkey;
74    long? enteredKey;
75  };
76
77  dictionary NewAdapterState {
78    // The human-readable name of the adapter.
79    DOMString? name;
80
81    // Whether or not the adapter has power.
82    boolean? powered;
83
84    // Whether the adapter is discoverable by other devices.
85    boolean? discoverable;
86  };
87
88  dictionary SetPairingResponseOptions {
89    // The remote device to send the pairing response.
90    bluetooth.Device device;
91
92    // The response type.
93    PairingResponse response;
94
95    // A 1-16 character alphanumeric set in response to
96    // <code>requestPincode</code>.
97    DOMString? pincode;
98
99    // An integer between 0-999999 set in response to
100    // <code>requestPasskey</code>.
101    long? passkey;
102  };
103
104  dictionary DiscoveryFilter {
105    // Transport type.
106    TransportType? transport;
107
108    // uuid of service or array of uuids
109    (DOMString or DOMString[])? uuids;
110
111    // RSSI ranging value. Only devices with RSSI higher than this value will be
112    // reported.
113    long? rssi;
114
115    // Pathloss ranging value. Only devices with pathloss lower than this value
116    // will be reported.
117    long? pathloss;
118  };
119
120  callback VoidCallback = void();
121  callback ConnectCallback = void(ConnectResultType result);
122
123  // These functions all report failures via chrome.runtime.lastError.
124  interface Functions {
125    // Changes the state of the Bluetooth adapter.
126    // |adapterState|: The new state of the adapter.
127    // |callback|: Called when all the state changes have been completed.
128    static void setAdapterState(NewAdapterState adapterState,
129                                optional VoidCallback callback);
130
131    static void setPairingResponse(SetPairingResponseOptions options,
132                                   optional VoidCallback callback);
133
134    // Tears down all connections to the given device.
135    static void disconnectAll(DOMString deviceAddress,
136                              optional VoidCallback callback);
137
138    // Forgets the given device.
139    static void forgetDevice(DOMString deviceAddress,
140                             optional VoidCallback callback);
141
142    // Set or clear discovery filter.
143    static void setDiscoveryFilter(DiscoveryFilter discoveryFilter,
144                                   optional VoidCallback callback);
145
146    // Connects to the given device. This will only throw an error if the
147    // device address is invalid or the device is already connected. Otherwise
148    // this will succeed and invoke |callback| with ConnectResultType.
149    static void connect(DOMString deviceAddress,
150                        optional ConnectCallback callback);
151
152    // Pairs the given device.
153    static void pair(DOMString deviceAddress, optional VoidCallback callback);
154
155    // Record that a pairing attempt finished. Ignores cancellations.
156    static void recordPairing(bluetooth.Transport transport,
157                              long pairingDurationMs,
158                              optional ConnectResultType result);
159
160    // Record that a user-initiated reconnection attempt to an already paired
161    // device finished. Ignores cancellations.
162    static void recordReconnection(optional ConnectResultType result);
163
164    // Record that a user selected a device to connect to.
165    static void recordDeviceSelection(long selectionDurationMs,
166                                      boolean wasPaired,
167                                      bluetooth.Transport transport);
168  };
169
170  interface Events {
171    // Fired when a pairing event occurs.
172    // |pairingEvent|: A pairing event.
173    [maxListeners=1] static void onPairing(PairingEvent pairingEvent);
174
175    // Fired when a Bluetooth device changed its address.
176    static void onDeviceAddressChanged(bluetooth.Device device,
177                                       DOMString oldAddress);
178  };
179};
180