Skip to main content

Module sync

Module sync 

Source
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:

Operationv1v2Feature
StatSTATSTA2stat_v2
List dirLIST→DENTLIS2ls_v2
Pull fileRECVRCV2sendrecv_v2
Push fileSENDSND2sendrecv_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 largest DATA chunk 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 → DENT response (v1).
DirEntryV2
Directory entry from a LIS2 response (v2).
FileMode
A Unix file mode as the sync protocol carries it: the file type and the permission bits in one number, e.g. 0o100644 for 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.
SyncFlags
Compression and behaviour flags for SND2 and RCV2, combined with |, with at most one compression flag among them.
SyncSession
A sync session over an open sync:\0 channel.

Enums§

SyncError
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 STA2 response carries after its id.
STAT_V2_SIZE
Size of a STA2 response: the four-byte id plus the body parse_stat_v2_body decodes.
SYNC_DATA_MAX
Maximum data payload in a single DATA message (64 KiB).

Functions§

open
Open a sync:\0 channel and return a SyncSession.
parse_stat_v2_body
Decode the body of a STA2 response — everything after its four-byte id.