1// Copyright 2020 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 5module location.nearby.connections.mojom; 6 7import "device/bluetooth/public/mojom/uuid.mojom"; 8import "mojo/public/mojom/base/file.mojom"; 9 10// Generic result status of NearbyConnections API calls. 11enum Status { 12 // The operation was successful. 13 kSuccess, 14 // The operation failed, without any more information. 15 kError, 16 // The app called an API method out of order (i.e. another method is expected 17 // to be called first). 18 kOutOfOrderApiCall, 19 // The app already has active operations (advertising, discovering, or 20 // connected to other devices) with another Strategy. Stop these operations on 21 // the current Strategy before trying to advertise or discover with a new 22 // Strategy. 23 kAlreadyHaveActiveStrategy, 24 // The app is already advertising; call StopAdvertising() before trying to 25 // advertise again. 26 kAlreadyAdvertising, 27 // The app is already discovering; call StopDiscovery() before trying to 28 // discover again. 29 kAlreadyDiscovering, 30 // An attempt to read from/write to a connected remote endpoint failed. If 31 // this occurs repeatedly, consider invoking DisconnectFromEndpoint(). 32 kEndpointIOError, 33 // An attempt to interact with a remote endpoint failed because it's unknown 34 // to us -- it's either an endpoint that was never discovered, or an endpoint 35 // that never connected to us (both of which are indicative of bad input from 36 // the client app). 37 kEndpointUnknown, 38 // The remote endpoint rejected the connection request. 39 kConnectionRejected, 40 // The app is already connected to the specified endpoint. Multiple 41 // connections to a remote endpoint cannot be maintained simultaneously. 42 kAlreadyConnectedToEndpoint, 43 // The remote endpoint is not connected; messages cannot be sent to it. 44 kNotConnectedToEndpoint, 45 // There was an error trying to use the device's Bluetooth capabilities. 46 kBluetoothError, 47 // There was an error trying to use the device's Bluetooth Low Energy 48 // capabilities. 49 kBleError, 50 // There was an error trying to use the device's WiFi capabilities. 51 kWifiLanError, 52 // An attempt to interact with an in-flight Payload failed because it's 53 // unknown to us. 54 kPayloadUnknown, 55}; 56 57// Information about a connection that is being initiated. 58struct ConnectionInfo { 59 // A short human-readable authentication token that has been given to both 60 // devices. 61 string authentication_token; 62 // The raw (significantly longer) version of the authentication token of 63 // authentication_token -- this is intended for headless authentication, 64 // typically on devices with no output capabilities, where the authentication 65 // is purely programmatic and does not have the luxury of human intervention. 66 array<uint8> raw_authentication_token; 67 // Information that represents the remote device. 68 array<uint8> endpoint_info; 69 // True if the connection request was initiated from a remote device. False if 70 // this device was the one to try and initiate the connection. 71 bool is_incoming_connection; 72}; 73 74// Information about an endpoint when it's discovered. 75struct DiscoveredEndpointInfo { 76 // Information advertised by the remote endpoint. 77 array<uint8> endpoint_info; 78 // The ID of the service advertised by the remote endpoint. 79 string service_id; 80}; 81 82// The Strategy to be used when discovering or advertising to Nearby devices. 83// The Strategy defines the connectivity requirements for the device, and the 84// topology constraints of the connection. 85enum Strategy { 86 // Peer-to-peer strategy that supports an M-to-N, or cluster-shaped, 87 // connection topology. In other words, this enables connecting amorphous 88 // clusters of devices within radio range (~100m), where each device can both 89 // initiate outgoing connections to M other devices and accept incoming 90 // connections from N other devices. 91 kP2pCluster, 92 // Peer-to-peer strategy that supports a 1-to-N, or star-shaped, connection 93 // topology. In other words, this enables connecting devices within radio 94 // range (~100m) in a star shape, where each device can, at any given time, 95 // play the role of either a hub (where it can accept incoming connections 96 // from N other devices), or a spoke (where it can initiate an outgoing 97 // connection to a single hub), but not both. 98 kP2pStar, 99 // Peer-to-peer strategy that supports a 1-to-1 connection topology. In other 100 // words, this enables connecting to a single device within radio range 101 // (~100m). This strategy will give the absolute highest bandwidth, but will 102 // not allow multiple connections at a time. 103 kP2pPointToPoint, 104}; 105 106// A selection of on/off toggles to define a set of allowed mediums. 107struct MediumSelection { 108 // Whether Bluetooth should be allowed. 109 bool bluetooth; 110 // Whether BLE should be allowed. 111 bool ble; 112 // Whether WebRTC should be allowed. 113 bool web_rtc; 114 // Whether WiFi LAN should be allowed. 115 bool wifi_lan; 116}; 117 118// Options for a call to NearbyConnections::StartAdvertising(). 119struct AdvertisingOptions { 120 // The strategy to use for advertising. Must match the strategy used in 121 // DiscoveryOptions for remote devices to see this advertisement. 122 Strategy strategy; 123 // Describes which mediums are allowed to be used for advertising. Note that 124 // allowing an otherwise unsupported medium is ok. Only the intersection of 125 // allowed and supported mediums will be used to advertise. 126 MediumSelection allowed_mediums; 127 // By default, this option is true. If false, we will not attempt to upgrade 128 // the bandwidth until a call to InitiateBandwidthUpgrade() is made. 129 bool auto_upgrade_bandwidth = true; 130 // By default, this option is true. If false, restrictions on topology will be 131 // ignored. This allows you treat all strategies as kP2pCluster (N to M), 132 // although bandwidth will be severely throttled if you don't maintain the 133 // original topology. When used in conjunction with auto_upgrade_bandwidth, 134 // you can initially connect as a kP2pCluster and then trim connections until 135 // you match kP2pStar or kP2pPointToPoint before upgrading the bandwidth. 136 bool enforce_topology_constraints = true; 137 // By default, this option is false. If true, this allows listening on 138 // incoming Bluetooth Classic connections while BLE advertising. 139 bool enable_bluetooth_listening = false; 140 // Optional. If set, BLE advertisements will be in their "fast advertisement" 141 // form, use this UUID, and non-connectable; if empty, BLE advertisements 142 // will otherwise be normal and connectable. 143 bluetooth.mojom.UUID fast_advertisement_service_uuid; 144}; 145 146// Options for a call to NearbyConnections::StartDiscovery(). 147struct DiscoveryOptions { 148 // The strategy to use for discovering. Must match the strategy used in 149 // AdvertisingOptions in order to see advertisements. 150 Strategy strategy; 151 // Describes which mediums are allowed to be used for scanning/discovery. Note 152 // that allowing an otherwise unsupported medium is ok. Only the intersection 153 // of allowed and supported mediums will be used to scan. 154 MediumSelection allowed_mediums; 155 // The fast advertisement service id to scan for in BLE. 156 bluetooth.mojom.UUID? fast_advertisement_service_uuid; 157 // Whether this connection request skips over the normal discovery flow to 158 // inject discovery information synced outside the Nearby Connections library. 159 // Intended to be used in conjunction with InjectEndpoint(). 160 bool is_out_of_band_connection = false; 161}; 162 163// Options for a call to NearbyConnections::RequestConnection(). 164struct ConnectionOptions { 165 // Describes which mediums are allowed to be used for connection. Note that 166 // allowing an otherwise unsupported medium is ok. Only the intersection of 167 // allowed and supported mediums will be used to connect. 168 MediumSelection allowed_mediums; 169 // Bluetooth MAC address of remote device in byte format. 170 array<uint8, 6>? remote_bluetooth_mac_address; 171}; 172 173// A simple payload containing raw bytes. 174struct BytesPayload { 175 // The bytes of this payload. 176 array<uint8> bytes; 177}; 178 179// A file payload representing a file. 180struct FilePayload { 181 // The file to which this payload points to. When sending this payload, the 182 // NearbyConnections library reads from this file. When receiving a file 183 // payload it writes to this file. 184 mojo_base.mojom.File file; 185}; 186 187// Union of all supported payload types. 188union PayloadContent { 189 // A Payload consisting of a single byte array. 190 BytesPayload bytes; 191 // A Payload representing a file on the device. 192 FilePayload file; 193}; 194 195// A Payload sent between devices. Payloads sent with a particular content type 196// will be received as that same type on the other device, e.g. the content for 197// a Payload of type BytesPayload must be received by reading from the bytes 198// field returned by Payload::content::bytes. 199struct Payload { 200 // A unique identifier for this payload. Generated by the sender of the 201 // payload and used to keep track of the transfer progress. 202 int64 id; 203 // The content of this payload which is one of multiple types, see 204 // PayloadContent for all possible types. 205 PayloadContent content; 206}; 207 208// The status of the payload transfer at the time of this update. 209enum PayloadStatus { 210 // The payload transfer has completed successfully. 211 kSuccess, 212 // The payload transfer failed. 213 kFailure, 214 // The payload transfer is still in progress. 215 kInProgress, 216 // The payload transfer has been canceled. 217 kCanceled, 218}; 219 220// Describes the status for an active Payload transfer, either incoming or 221// outgoing. Delivered to PayloadListener::OnPayloadTransferUpdate. 222struct PayloadTransferUpdate { 223 // The ID for the payload related to this update. Clients should match this 224 // with Payload::id. 225 int64 payload_id; 226 // The status of this payload transfer. Always starts with kInProgress and 227 // ends with one of kSuccess, kFailure or kCanceled. 228 PayloadStatus status; 229 // The total expected bytes of this transfer. 230 uint64 total_bytes; 231 // The number of bytes transferred so far. 232 uint64 bytes_transferred; 233}; 234 235// Bandwidth quality of a connection. 236enum BandwidthQuality { 237 // Unknown connection quality. 238 kUnknown, 239 // Low quality, e.g. connected via NFC or BLE. 240 kLow, 241 // Medium quality, e.g. connected via Bluetooth Classic. 242 kMedium, 243 // High quality, e.g. connected via WebRTC or WiFi LAN. 244 kHigh, 245}; 246 247// These values are persisted to logs. Entries should not be renumbered and 248// numeric values should never be reused. 249enum Medium { 250 kUnknown = 0, 251 kMdns = 1, 252 kBluetooth = 2, 253 kWifiHotspot = 3, 254 kBle = 4, 255 kWifiLan = 5, 256 kWifiAware = 6, 257 kNfc = 7, 258 kWifiDirect = 8, 259 kWebRtc = 9, 260}; 261