6.1 KiB
@yume-chan/adb
TypeScript implementation of Android Debug Bridge (ADB) protocol.
Connection
This library doesn't tie with a specific transportation method.
Instead, a Backend is responsible for transferring packets in its own way (USB, WebSocket, etc).
Backend
read
read(length: number): ArrayBuffer | Promise<ArrayBuffer>
Read the specified amount of data from the underlying connection.
The backend should return only the data written by another endpoint in a single operation. That meas, it should never concatenate multiple write operations to fulfill the requested length. Here is the reason:
In normal working condition the client always knows how much data it should read and the server will always send exactly such amount of data in a single operation.
One exception is that for stateless connections (including USB and TCP), if one client sent a request and died without reading the response, the data will sit in an operating system's internal buffer. When the next client, reusing the connection, want to read a response to its request, it may get that buffered response instead.
The native ADB implementation tries to detect such a situation by checking length and content of the response data, so do this library. So the backend should not return such a response if possible, or follow this behavior if it can't distinguish.
write
write(buffer: ArrayBuffer): void | Promise<void>
Write data to the underlying connection.
Authenticate
ADB supports two authentication methods:
Public key authentication
- Client (this library) generates a RSA private key and save it.
- Client generates an ADB public key (not RSA public key) based on the RSA private key.
- Client transfers the ADB public key to server (device).
- Server may ask its user to accept the public key, it will save the public key if accepted.
Backend
generateKey
generateKey(): ArrayBuffer | Promise<ArrayBuffer>
Generate and store a RSA private key with modulus length 2048 and public exponent 65537.
The returned ArrayBuffer is the private key in PKCS #8 format.
Token authentication
- Server transfers a 20 bytes token to client.
- Client RSA encrypts the token with its RSA private key.
- Client transfers the encrypted token to server.
- Server tries to decrypt the received data with all saved public keys. If any decryption succeed, the authentication succeed.
Backend
iterateKeys
generateKey(): Iterator<ArrayBuffer> | AsyncIterator<ArrayBuffer>
Synchronously or asynchronously iterate through all stored RSA private keys.
Each call to iterateKeys must returns a different iterator that iterate through all stored keys.
Stream multiplex
ADB commands are all based on streams. Multiple streams can send and receive at the same time in one connection.
- Client sends an
OPENpacket to create a stream. - Server responds with
OKAYorFAIL. - Client and server read/write on the stream.
- Client/server sends a
CLSEto close the stream.
The Backend is responsible for encoding and decoding UTF-8 strings.
Backend
encodeUtf8
encodeUtf8(input: string): ArrayBuffer
Encode input into an ArrayBuffer with UTF-8 encoding.
decodeUtf8
decodeUtf8(buffer: ArrayBuffer): string
Decode buffer into a string with UTF-8 encoding.
Commands
shell
PTY mode
Basic mode, supported on all devices.
ADB shell protocol
(Not Implemented)
Supported on devices with shell_v2 feature.
Supports window size changing event.
Supports returning process exit code.
Raw mode
(Not Implemented)
Must be used with ADB shell protocol.
Supports splitting stdout and stderr.
usb
Disable ADB over WiFi.
tcpip
Enable ADB over WiFi.
sync
Client and server will communicate with another protocol on the opened stream.
LIST
Request server to list the content of a folder.
LIS2
(Not Implemented)
Version 2 of the LIST command, contains more information.
Supported on devices with ls_v2 feature.
STAT
Request server to return the information of a file.
If path is a symbolic link, the returned information is about the link itself.
So it's actually the lstat system call.
LST2
Version 2 of the STAT command, contains more information.
Supported on devices with stat_v2 feature.
STA2
Basically identical to LST2, but if path is a symbolic link, the information is about the file it refers to.
Supported on devices with stat_v2 feature.
RECV
Request server to send the content of a file.
RCV2
(Not Implemented)
Version 2 of the RECV command.
Supported on devices with sendrecv_v2 feature.
SEND
(Not Implemented)
Send a file onto server's file system.
SND2
(Not Implemented)
Version 2 of the SEND command.
Supported on devices with sendrecv_v2 feature.