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