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