Expand description
ADB sync protocol — file operations (stat, list, push, pull).
The sync protocol operates over a sync:\0 channel and provides
file-system access on the device. Each message uses an 8-byte
header: [id: 4 ASCII bytes, arg: u32 LE], optionally followed
by a variable-length payload.
This module supports both legacy (v1) and extended (v2) variants:
| Operation | v1 | v2 | Feature |
|---|---|---|---|
| Stat | STAT | STA2 | stat_v2 |
| List dir | LIST→DENT | LIS2 | ls_v2 |
| Pull file | RECV | RCV2 | sendrecv_v2 |
| Push file | SEND | SND2 | sendrecv_v2 |
Each of the SyncFlags RCV2 and SND2 carry needs a feature of
its own on top of sendrecv_v2.
§Paths
adbd keeps a path in a C string, so a NUL would end it early. SND2
and the requests that only read would act on the file named before
the NUL, with no error. SEND would lose the mode that follows the
path: adbd fails with missing , in ID_SEND_V1 and ends the service,
unless a comma comes before the NUL, which it then takes for the one
before the mode.
So every call that takes a path fails with
SyncError::InvalidPath on a NUL, before anything is sent and
before it looks at what the device advertises. The session stays
usable.
§A push the device fails
adbd answers some pushes with FAIL and ends the sync service
before it has read them through, a path over 1024 bytes for one. A
push call that then finds the channel closed fails with the
SyncError::Failed the device sent, and with
Error::ChannelClosed only if it sent none. Either way it waits
for nothing more from the device.
§Buffer sizing
SyncSession uses a caller-provided byte slice as its receive
buffer. The minimum useful size depends on the operation:
- stat / stat_v2: 72 bytes.
- list / list_v2: 76 bytes + longest file name.
- recv / send:
HEADER_SIZE+SYNC_DATA_MAX= 65 544 bytes to fit the largestDATAchunk the device may send.
Passing a buffer that is too small yields
Error::ReceiveBufferFull — except for a FAIL body, which is
truncated to the buffer instead so the device’s error is never
masked by a buffer complaint.
§Examples
let mut buf = [0u8; 66_000];
let mut sync = sync::open(&mut conn, &mut buf).await?;
// stat
let st = sync.stat_v2("/sdcard/DCIM").await?;
// list
for entry in sync.list_v2("/sdcard/DCIM").await? {
println!("{}", core::str::from_utf8(&entry.name).unwrap());
}
// pull (small file)
let data = sync.recv("/sdcard/file.txt").await?;
// push
sync.send("/sdcard/upload.txt", FileMode(0o100644), 0, b"hello").await?;
sync.quit().await?;Structs§
- DirEntry
- Directory entry from a
LIST→DENTresponse (v1). - DirEntry
V2 - Directory entry from a
LIS2response (v2). - File
Mode - A Unix file mode as the sync protocol carries it: the file type and
the permission bits in one number, e.g.
0o100644for a regular file its owner may write and anyone may read. - StatV1
- File metadata from a
STAT(v1) response. - StatV2
- File metadata from a
STA2(v2) response. - Sync
Flags - Compression and behaviour flags for
SND2andRCV2, combined with|, with at most one compression flag among them. - Sync
Session - A sync session over an open
sync:\0channel.
Enums§
- Sync
Error - What a sync request fails with: what the service answered instead of
what was asked, be it a
FAIL, a reply the session did not expect or an errno in a v2 stat or listing, or flags or a path the session did not send because adbd would refuse or misread them.
Constants§
- HEADER_
SIZE - Size of the basic sync header:
id(4) + arg(4). - STAT_
V2_ BODY_ SIZE - Size of the body a
STA2response carries after its id. - STAT_
V2_ SIZE - Size of a
STA2response: the four-byte id plus the bodyparse_stat_v2_bodydecodes. - SYNC_
DATA_ MAX - Maximum data payload in a single
DATAmessage (64 KiB).
Functions§
- open
- Open a
sync:\0channel and return aSyncSession. - parse_
stat_ v2_ body - Decode the body of a
STA2response — everything after its four-byte id.