Skip to main content

Crate adb

Crate adb 

Source
Expand description

C ABI for libadb.

The API is synchronous from the caller’s perspective: each async operation is driven to completion by a tiny internal executor. No tokio or smol runtime is required.

include/libadb.h is the contract: it says in full what each call does and returns, how it fails, what stays valid and what the caller must do. The rustdoc here gives a summary and the # Safety section.

Under the hood a handle is a split Reader / Writer pair sharing a reference-counted state. A write never waits for the Reader’s mutex, so a thread blocked in a long read does not prevent another thread from writing — which is what makes interactive shell sessions usable from C without any async runtime.

Reader::run is never started, so only a call holding the read lock takes packets off the connection, and that includes the OKAY Writer::write_channel waits for. A write waiting for the device with no read call running reads the connection itself, under that lock. A read does not wait for the lock: finding it taken, the read takes what the holder dispatches for its channel, and the lock once it comes free.

§Feature flags

TCP support is always compiled in and needs no async runtime. USB support is opt-in: enable usb (alias for the pure-Rust nusb backend) or rusb (libusb). Both may be on at once, and usb:// then goes to nusb, since adb_connect cannot choose a backend.

tls answers a wireless-debugging device’s STLS (Android 11+) from adb_connect with TLS 1.3, presenting the caller’s key in a certificate; without it such a device is AdbStatus::TlsRequired. adb_connect_with_authenticator stays in the clear either way.

pairing (implies tls) adds adb_pair, the adb pair exchange against the device’s pairing dialog: the one way to put a key on a device that has never seen it without a USB cable.

Structs§

adb_authenticator_t
Caller-supplied authenticator passed to adb_connect_with_authenticator.
adb_connection_t
Opaque connection handle.
adb_key_t
An RSA host key loaded from, or generated into, a key directory.
adb_shell_t
Opaque shell_v2 session handle.

Enums§

AdbStatus
Status code returned by most FFI entry points.

Functions§

adb_accept_channel⚠
Report the staged device-initiated channel (adb reverse traffic), waiting for one to arrive if none is staged, and copy its destination into (dest, dest_cap, out_dest_len) per adb_connection_features. The request stays staged on the handle until adb_incoming_accept or adb_incoming_reject takes it, so repeated calls report the same request again. See libadb.h.
adb_close_channel⚠
Close a channel. Subsequent reads/writes against this ID will fail with AdbStatus::ChannelClosed. See libadb.h.
adb_connect⚠
Parse uri, open a transport, and perform the CNXN/AUTH handshake. On success *out is set to a freshly-allocated handle that must be released with adb_connection_free.
adb_connect_with_authenticator⚠
Like adb_connect, but uses a caller-supplied adb_authenticator_t instead of the built-in RSA/PEM authenticator, for a private key that lives outside the host process.
adb_connection_delayed_ack⚠
Whether delayed-ACK (credit-based flow control) was negotiated; false if conn is NULL.
adb_connection_device_banner⚠
Copy the device banner bytes into buf (up to buf_len bytes) and write the full banner length through out_len, so a caller whose buffer was too short can retry with a larger one.
adb_connection_features⚠
Copy up to buf_cap features advertised by the device into buf (in handshake order) and write the full count through out_len. Either pointer may be NULL; pass (NULL, 0, &n) to query the count, then call again with a larger buffer.
adb_connection_free⚠
Release a handle from adb_connect or adb_connect_with_authenticator. NULL is a no-op.
adb_connection_has_feature⚠
Whether the device advertises feature.
adb_connection_max_payload⚠
Negotiated maximum payload size, in bytes; 0 if conn is NULL.
adb_connection_set_io_timeout_ms⚠
Set the receive and send timeouts of a tcp:// connection, in milliseconds; 0 disables that timeout. USB transports answer AdbStatus::InvalidArg.
adb_feature_name
Wire-format name of feature (e.g. "shell_v2") as a static NUL-terminated string, or NULL if feature is not one of the ADB_FEATURE_* constants defined in libadb.h.
adb_incoming_accept⚠
Accept the channel staged by adb_accept_channel, returning its ID through out_id.
adb_incoming_reject⚠
Reject the channel staged by adb_accept_channel.
adb_key_free⚠
Release a handle from adb_key_load_or_generate. NULL is a no-op.
adb_key_load_or_generate⚠
Load <android_dir>/adbkey, generating and persisting a key when there is none. name is the user@host comment shown in the device’s authorization dialog; NULL picks a default. On success *out receives a handle to release with adb_key_free. See libadb.h.
adb_key_private_key_pem⚠
The PKCS#8 PEM private key, ready to pass to adb_connect; NULL if key is NULL. The string is owned by key and stays valid until adb_key_free.
adb_key_public_key⚠
The ADB-format public key — the adbkey.pub line — ready to pass to adb_connect; NULL if key is NULL. The string is owned by key and stays valid until adb_key_free.
adb_last_error
Return a pointer to a C string describing the last error that occurred on this thread, or NULL if no error is set.
adb_open_channel⚠
Open a new channel to destination, an ADB service string such as "shell:ls" that need not be null-terminated. On success *out_id receives a 64-bit channel ID for the other adb_*_channel functions. See libadb.h.
adb_pair⚠pairing
Pair with a device: put the key in priv_key_pem into its trusted store through “Pair device with pairing code” on its Wireless debugging screen (SPAKE2 inside TLS, as adb pair does).
adb_read_channel⚠
Read from a channel into buf (up to buf_len bytes). Writes the number of bytes actually read through out_read.
adb_reverse_forward⚠
Establish a reverse forward: the device listens on device_spec and opens a channel toward the host for each connection, with host_spec as its destination. Receive those channels with adb_accept_channel.
adb_reverse_list⚠
List the device’s reverse rules, whichever connection established them, as <serial> <remote> <local>\n lines, into (buf, buf_len, out_len) per adb_connection_features. The lines are the device’s own bytes, passed on unparsed.
adb_reverse_remove⚠
Remove the reverse rule listening on device_spec, whichever connection established it.
adb_reverse_remove_all⚠
Remove every reverse rule on the device, whichever connection established it.
adb_shell_close⚠
Close the underlying channel. Subsequent read/write ops on this handle return AdbStatus::ChannelClosed. Idempotent.
adb_shell_close_stdin⚠
Send a CLOSE_STDIN frame — no more stdin will follow. A channel the device has already closed is not a failure. See libadb.h.
adb_shell_free⚠
Release a handle previously returned by adb_shell_open. NULL is a no-op. The channel is not closed automatically: call adb_shell_close first to avoid leaking it on the device.
adb_shell_open⚠
Open a shell_v2 session running command, which must be UTF-8 and need not be null-terminated. With pty the session gets a PTY, with term for its TERM and rows and cols for its window size.
adb_shell_read_frame⚠
Read one decoded shell_v2 frame: *out_id receives the frame id, buf up to buf_cap bytes of payload and *out_len the full payload length. Channel closure is AdbStatus::ChannelClosed. See libadb.h.
adb_shell_set_window_size⚠
Send a WINDOW_SIZE_CHANGE frame.
adb_shell_write_stdin⚠
Send a STDIN frame. Safe to call from several threads on one session: frames arrive whole. After a failure the session’s frame stream cannot be trusted: close it. See libadb.h.
adb_write_channel⚠
Write buf_len bytes from buf to a channel. Returns only after all bytes have been framed and handed to the transport.

Type Aliases§

AdbSignFn
C-callable signing callback, adb_sign_fn in libadb.h.