update request permission chapter

tango-adb · Dec 30, 2023 · f7e0818 · f7e0818
1 parent 1df2b1b
commit f7e0818
Show file tree

Hide file tree

Showing 35 changed files with 524 additions and 982 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -40,5 +40,8 @@
     ],
     "yaml.schemas": {
         "https://json.schemastore.org/github-workflow.json": ".github/workflows/deploy.yml"
-    }
+    },
+    "cSpell.enableFiletypes": [
+        "mdx"
+    ]
 }
diff --git a/docs/tango/commands/framebuffer.mdx → docs/api/framebuffer.mdx b/docs/tango/commands/framebuffer.mdx → docs/api/framebuffer.mdx
diff --git a/docs/tango/commands/get-prop.md → docs/api/get-prop.md b/docs/tango/commands/get-prop.md → docs/api/get-prop.md
diff --git a/docs/tango/commands/index.mdx → docs/api/index.mdx b/docs/tango/commands/index.mdx → docs/api/index.mdx
diff --git a/docs/tango/commands/power.md → docs/api/power.md b/docs/tango/commands/power.md → docs/api/power.md
diff --git a/docs/tango/commands/reverse.mdx → docs/api/reverse.mdx b/docs/tango/commands/reverse.mdx → docs/api/reverse.mdx
diff --git a/docs/tango/commands/rm.md → docs/api/rm.md b/docs/tango/commands/rm.md → docs/api/rm.md
diff --git a/docs/tango/commands/subprocess.mdx → docs/api/subprocess.mdx b/docs/tango/commands/subprocess.mdx → docs/api/subprocess.mdx
diff --git a/docs/tango/commands/sync/_category_.yml → docs/api/sync/_category_.yml b/docs/tango/commands/sync/_category_.yml → docs/api/sync/_category_.yml
diff --git a/docs/tango/commands/sync/index.mdx → docs/api/sync/index.mdx b/docs/tango/commands/sync/index.mdx → docs/api/sync/index.mdx
diff --git a/docs/tango/commands/sync/isDirectory.md → docs/api/sync/isDirectory.md b/docs/tango/commands/sync/isDirectory.md → docs/api/sync/isDirectory.md
diff --git a/docs/tango/commands/sync/opendir.mdx → docs/api/sync/opendir.mdx b/docs/tango/commands/sync/opendir.mdx → docs/api/sync/opendir.mdx
diff --git a/docs/tango/commands/sync/read.mdx → docs/api/sync/read.mdx b/docs/tango/commands/sync/read.mdx → docs/api/sync/read.mdx
diff --git a/docs/tango/commands/sync/stat.md → docs/api/sync/stat.md b/docs/tango/commands/sync/stat.md → docs/api/sync/stat.md
diff --git a/docs/tango/commands/sync/write.md → docs/api/sync/write.md b/docs/tango/commands/sync/write.md → docs/api/sync/write.md
diff --git a/docs/tango/commands/tcpip.md → docs/api/tcpip.md b/docs/tango/commands/tcpip.md → docs/api/tcpip.md
diff --git a/docs/internal/index.md b/docs/internal/index.md
@@ -7,7 +7,7 @@ sidebar_position: 0
 
 [ADB (Android Debugging Bridge)](https://developer.android.com/studio/command-line/adb) is the protocol for communicating with Android devices.
 
-This is an unofficial book about it.
+This section documents some internal mechanics in Google ADB.
 
 ## Links
 

diff --git a/docs/scrcpy/prepare-server.mdx b/docs/scrcpy/prepare-server.mdx
@@ -2,6 +2,9 @@
 sidebar_position: 2
 ---
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 # Prepare the server binary
 
 Scrcpy server is a Java application that runs on Android devices. Tango uses the unmodified, official Scrcpy server binary, so you don't need to build it yourself.
@@ -26,17 +29,15 @@ Assume you have downloaded the server binary to `src/server.bin`, and you want t
 
 ```ts transpile
 const url = new URL("./server.bin", import.meta.url);
-const server: ArrayBuffer = await fetch(url)
-    .then((res) => res.arrayBuffer())
+const server: ArrayBuffer = await fetch(url).then((res) => res.arrayBuffer());
 ```
 
     </TabItem>
     <TabItem label="Vite" value="vite">
 
 ```ts transpile
 const url = new URL("./server.bin", import.meta.url);
-const server: ArrayBuffer = await fetch(url)
-    .then((res) => res.arrayBuffer())
+const server: ArrayBuffer = await fetch(url).then((res) => res.arrayBuffer());
 ```
 
     </TabItem>
@@ -46,10 +47,11 @@ const server: ArrayBuffer = await fetch(url)
 import fs from "fs/promises";
 
 const url = new URL("./server.bin", import.meta.url);
-const server: Buffer = fs.readFile(url)
+const server: Buffer = fs.readFile(url);
 ```
 
     </TabItem>
+
 </Tabs>
 
 ## Use `@yume-chan/fetch-scrcpy-server`
@@ -74,8 +76,8 @@ The server binary is written to `server.bin` and the version is written to `vers
 
 Importing this package will give you two variables:
 
-* `BIN`: A URL to the server binary. It can be used in `fetch` or `fs.readFile` similar to the manual approach.
-* `VERSION`: A string containing the downloaded server version. It's required when starting the server.
+- `BIN`: A URL to the server binary. It can be used in `fetch` or `fs.readFile` similar to the manual approach.
+- `VERSION`: A string containing the downloaded server version. It's required when starting the server.
 
 <Tabs className="runtime-tabs" groupId="bundler">
     <TabItem label="Webpack 5" value="webpack-5">
@@ -84,8 +86,7 @@ Importing this package will give you two variables:
 import { BIN, VERSION } from "@yume-chan/fetch-scrcpy-server";
 
 console.log(VERSION); // 2.1
-const server: ArrayBuffer = await fetch(BIN)
-    .then((res) => res.arrayBuffer())
+const server: ArrayBuffer = await fetch(BIN).then((res) => res.arrayBuffer());
 ```
 
     </TabItem>
@@ -95,8 +96,7 @@ const server: ArrayBuffer = await fetch(BIN)
 import { BIN, VERSION } from "@yume-chan/fetch-scrcpy-server";
 
 console.log(VERSION); // 2.1
-const server: ArrayBuffer = await fetch(BIN)
-    .then((res) => res.arrayBuffer())
+const server: ArrayBuffer = await fetch(BIN).then((res) => res.arrayBuffer());
 ```
 
     </TabItem>
@@ -106,10 +106,11 @@ const server: ArrayBuffer = await fetch(BIN)
 import { BIN, VERSION } from "@yume-chan/fetch-scrcpy-server";
 
 console.log(VERSION); // 2.1
-const server: Buffer = fs.readFile(BIN)
+const server: Buffer = fs.readFile(BIN);
 ```
 
     </TabItem>
+
 </Tabs>
 
 ### Run the script automatically
@@ -118,9 +119,9 @@ After installing the package, you can add it to your NPM scripts, so every time
 
 ```json
 {
-    "scripts": {
-        "postinstall": "fetch-scrcpy-server 2.1"
-    }
+  "scripts": {
+    "postinstall": "fetch-scrcpy-server 2.1"
+  }
 }
 ```
 
@@ -129,9 +130,10 @@ After installing the package, you can add it to your NPM scripts, so every time
 The easiest way to modify and build the server is to use [Android Studio](https://developer.android.com/studio).
 
 1. Clone Scrcpy
-    ```sh
-    git clone https://github.com/Genymobile/scrcpy.git
-    ```
+
+   ```sh
+   git clone https://github.com/Genymobile/scrcpy.git
+   ```
 
 2. Open the root folder in Android Studio
 3. (Optional) Change `Build Variant` to `release` from `Build` -> `Select Build Variant` menu item

diff --git a/docs/scrcpy/push-server.mdx b/docs/scrcpy/push-server.mdx
@@ -18,7 +18,7 @@ adb push scrcpy-server.jar /data/local/tmp/scrcpy-server.jar
 
 ## Using `pushServer`
 
-`@yume-chan/adb-scrcpy` package provides a `pushServer` function as a shortcut for the Tango [`AdbSync#write`](../tango/commands/sync/write.md) call.
+`@yume-chan/adb-scrcpy` package provides a `pushServer` function as a shortcut for the Tango [`AdbSync#write`](../api/sync/write.md) call.
 
 ```ts transpile
 import type { Adb } from "@yume-chan/adb";

diff --git a/docs/tango/commands/_category_.yml b/docs/tango/commands/_category_.yml
diff --git a/docs/tango/custom-transport.mdx b/docs/tango/custom-transport.mdx
@@ -82,7 +82,7 @@ Other fields:
 - `maxPayloadSize`: The maximum payload size of the device. `AdbSync#write` will split data into multiple packets if it's larger than this value. If you don't know this value, use 4KB.
 - `banner`: ADB banner returned from the device. It contains the list of ADB features the device supports, which is important for many command to choose the correct behavior.
 - `disconnected`: A promise that resolves when the transport is disconnected.
-- `addReverseTunnel`, `removeReverseTunnel`, `clearReverseTunnels`: These methods are used to manage reverse tunnels. When a reverse tunnel is created, Tango sends the correct command to ADB daemon via `connect` method, but also calls `addReverseTunnel` method. The transport should register the reverse tunnel, so when ADB daemon creates a socket to the tunnel address, the `handler` method will be invoked. If the transport doesn't support reverse tunnel, it should throw an error from `addReverseTunnel` method. See [Reverse Tunnel](./commands/reverse.mdx) for more details.
+- `addReverseTunnel`, `removeReverseTunnel`, `clearReverseTunnels`: These methods are used to manage reverse tunnels. When a reverse tunnel is created, Tango sends the correct command to ADB daemon via `connect` method, but also calls `addReverseTunnel` method. The transport should register the reverse tunnel, so when ADB daemon creates a socket to the tunnel address, the `handler` method will be invoked. If the transport doesn't support reverse tunnel, it should throw an error from `addReverseTunnel` method. See [Reverse Tunnel](../api/reverse.mdx) for more details.
 - `close`: Close the transport. It should close all sockets created by `connect` method, and resolve `disconnected` promise.
 
 ## Example

diff --git a/docs/tango/daemon/connect-device.mdx b/docs/tango/daemon/connect-device.mdx
@@ -40,6 +40,6 @@ const adb: Adb = new Adb(transport);
 
 :::note[Next Step]
 
-See [commands](../commands/index.mdx) for how to use the `Adb` instance.
+See [commands](../../api/index.mdx) for how to use the `Adb` instance.
 
 :::
diff --git a/docs/tango/daemon/custom-connection.mdx b/docs/tango/daemon/custom-connection.mdx
@@ -12,7 +12,7 @@ You may also interested in [custom transports](../custom-transport.mdx), which w
 
 :::
 
-We have seen [`AdbDaemonWebUsbDevice`](./usb/get-devices.md) class in USB connection and [`AdbDaemonDirectSocketsDevice`](./tcp/create-connection.mdx#adbdaemondirectsocketsdevice) class in TCP connection, but they are high-level abstractions for managing devices. In fact, `AdbDaemonTransport` only needs a pair of [`ReadableStream<AdbPacket>`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WriteableStream<Consumable<AdbPacket>>`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to work, that's what the `connect` method in those `Device` classes returns.
+We have seen [`AdbDaemonWebUsbDevice`](./usb/get-devices.mdx) class in USB connection and [`AdbDaemonDirectSocketsDevice`](./tcp/create-connection.mdx#adbdaemondirectsocketsdevice) class in TCP connection, but they are high-level abstractions for managing devices. In fact, `AdbDaemonTransport` only needs a pair of [`ReadableStream<AdbPacket>`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WriteableStream<Consumable<AdbPacket>>`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to work, that's what the `connect` method in those `Device` classes returns.
 
 :::note
 

diff --git a/docs/tango/daemon/tcp/enable.md b/docs/tango/daemon/tcp/enable.md
@@ -40,6 +40,6 @@ On non-rooted devices with Android 10 and below, enabling ADB over WiFi requires
 
   `5555` is the port ADB daemon will listen at, and can be freely changed.
 
-- To enable ADB over WiFI using Tango, use the [`tcpip` command](../../commands/tcpip.md).
+- To enable ADB over WiFI using Tango, use the [`tcpip` command](../../../api/tcpip.md).
 
 When device is restarted, ADB over WiFi will be disabled. To re-enable it, connect the device using a USB cable and follow the steps above again.
diff --git a/docs/tango/daemon/usb/get-devices.md → docs/tango/daemon/usb/get-devices.mdx b/docs/tango/daemon/usb/get-devices.md → docs/tango/daemon/usb/get-devices.mdx
@@ -7,22 +7,26 @@ import TabItem from "@theme/TabItem";
 
 # Get all connected devices
 
-## Get devices
-
 <Tabs className="runtime-tabs" groupId="runtime">
 <TabItem value="web" label="Web">
 
-WebUSB's [`USB#getDevices`](https://developer.mozilla.org/en-US/docs/Web/API/USB/getDevices) method returns all devices that are currently connected and have been granted permission to access by the user.
+After the user has granted permission to access the device, the next time the user visits the page, the Web app can access the device directly without asking for permission again.
 
 </TabItem>
 <TabItem value="node" label="Node.js">
 
-Previously, we have disabled the permission system in `usb` package's WebUSB implementation, so the [`USB#getDevices`](https://developer.mozilla.org/en-US/docs/Web/API/USB/getDevices) method returns all devices that are currently connected.
+Previously, we have disabled the permission system in `usb` package's WebUSB implementation, so it will return all devices that are currently connected.
 
 </TabItem>
 </Tabs>
 
-`USB#getDevices` returns all connected devices, including those that are not ADB devices. So `AdbDaemonWebUsbDeviceManager#getDevices` method calls `USB#getDevices`, picks ADB devices from the results, and wraps them to `AdbDaemonWebUsbDevice` instances.
+The app can get all connected devices by calling `AdbDaemonWebUsbDeviceManager#getDevices` method. It can then connect to multiple devices at the same time, or let the user choose one device to connect to.
+
+## Get devices
+
+`AdbDaemonWebUsbDeviceManager#getDevices` method calls WebUSB's `USB#getDevices` method to get all connected devices.
+
+But since `USB#getDevices` returns all connected devices, including those that are not ADB devices, `AdbDaemonWebUsbDeviceManager#getDevices` accepts a `filters` option (same as `AdbDaemonWebUsbDeviceManager#requestDevice`) to filter out incompatible devices.
 
 ```ts
 interface AdbDeviceFilter {
@@ -39,6 +43,18 @@ declare class AdbDaemonWebUsbDeviceManager {
 }
 ```
 
+The `filters` option is optional and defaults to `ADB_DEFAULT_DEVICE_FILTER`, which picks common ADB devices:
+
+```ts
+export const ADB_DEFAULT_DEVICE_FILTER = {
+  classCode: 0xff,
+  subclassCode: 0x42,
+  protocolCode: 1,
+} as const satisfies AdbDeviceFilter;
+```
+
+So in many cases, you can just call `AdbDaemonWebUsbDeviceManager#getDevices` without any arguments:
+
 ```ts transpile
 import { AdbDaemonWebUsbDevice } from "@yume-chan/adb-daemon-webusb";
 
@@ -53,17 +69,7 @@ const device: AdbDaemonWebUsbDevice = devices[0];
 
 ## Filter connected devices
 
-By default, `AdbDaemonWebUsbDeviceManager#getDevices` method uses a filter that matches the ADB interface:
-
-```ts
-export const ADB_DEFAULT_DEVICE_FILTER = {
-  classCode: 0xff,
-  subclassCode: 0x42,
-  protocolCode: 1,
-} as const satisfies AdbDeviceFilter;
-```
-
-But it also accepts custom filters to limit which devices will be returned. Each filter is an object with the following fields:
+To limit which devices will be returned, you can specify multiple custom filters. Each filter is an object with the following fields:
 
 - `classCode`: (Required) The class code of the ADB interface.
 - `subclassCode`: (Required) The subclass code of the ADB interface.
@@ -82,11 +88,7 @@ Some lazy manufacturers use the same `serialNumber` for all devices. So even if
 
 :::
 
-To say a device matches a filter, the device must match all specified fields in the filter.
-
-To say a device matches multiple filters, the device must match at least one of them.
-
-For example, to only allow a specific manufacturer/model:
+If a filter has multiple fields, the device must match all fields to be returned. For example, this filter only allows a specific manufacturer/model:
 
 ```ts transpile
 import {
@@ -103,7 +105,7 @@ const devices: AdbDaemonWebUsbDevice[] = await Manager.getDevices([
 ]);
 ```
 
-And to allow multiple manufacturers/models:
+If multiple filters are specified, any device matching at least one filter will be returned. So, to allow multiple manufacturers/models:
 
 ```ts transpile
 import {

diff --git a/docs/tango/daemon/usb/monitor-devices.mdx b/docs/tango/daemon/usb/monitor-devices.mdx
@@ -28,4 +28,4 @@ const watcher = new AdbDaemonWebUsbDeviceWatcher(
 watcher.dispose();
 ```
 
-Generally, the handler should reload the device list using [`AdbDaemonWebUsbDeviceManager#getDevices`](./get-devices.md) and update the UI.
+Generally, the handler should reload the device list using [`AdbDaemonWebUsbDeviceManager#getDevices`](./get-devices.mdx) and update the UI.
-Original file line number
+Diff line change
@@ Expand Up @@
     :::
-    We have seen [`AdbDaemonWebUsbDevice`](./usb/get-devices.md) class in USB connection and [`AdbDaemonDirectSocketsDevice`](./tcp/create-connection.mdx#adbdaemondirectsocketsdevice) class in TCP connection, but they are high-level abstractions for managing devices. In fact, `AdbDaemonTransport` only needs a pair of [`ReadableStream<AdbPacket>`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WriteableStream<Consumable<AdbPacket>>`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to work, that's what the `connect` method in those `Device` classes returns.
+    We have seen [`AdbDaemonWebUsbDevice`](./usb/get-devices.mdx) class in USB connection and [`AdbDaemonDirectSocketsDevice`](./tcp/create-connection.mdx#adbdaemondirectsocketsdevice) class in TCP connection, but they are high-level abstractions for managing devices. In fact, `AdbDaemonTransport` only needs a pair of [`ReadableStream<AdbPacket>`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WriteableStream<Consumable<AdbPacket>>`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to work, that's what the `connect` method in those `Device` classes returns.
     :::note
@@ Expand Down @@