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 reversetraffic), waiting for one to arrive if none is staged, and copy its destination into(dest, dest_cap, out_dest_len)peradb_connection_features. The request stays staged on the handle untiladb_incoming_acceptoradb_incoming_rejecttakes it, so repeated calls report the same request again. Seelibadb.h. - adb_
close_ ⚠channel - Close a channel. Subsequent reads/writes against this ID will fail
with
AdbStatus::ChannelClosed. Seelibadb.h. - adb_
connect ⚠ - Parse
uri, open a transport, and perform the CNXN/AUTH handshake. On success*outis set to a freshly-allocated handle that must be released withadb_connection_free. - adb_
connect_ ⚠with_ authenticator - Like
adb_connect, but uses a caller-suppliedadb_authenticator_tinstead 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;
falseifconnis NULL. - adb_
connection_ ⚠device_ banner - Copy the device banner bytes into
buf(up tobuf_lenbytes) and write the full banner length throughout_len, so a caller whose buffer was too short can retry with a larger one. - adb_
connection_ ⚠features - Copy up to
buf_capfeatures advertised by the device intobuf(in handshake order) and write the full count throughout_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_connectoradb_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
connis 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 answerAdbStatus::InvalidArg. - adb_
feature_ name - Wire-format name of
feature(e.g."shell_v2") as a static NUL-terminated string, or NULL iffeatureis not one of theADB_FEATURE_*constants defined inlibadb.h. - adb_
incoming_ ⚠accept - Accept the channel staged by
adb_accept_channel, returning its ID throughout_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.nameis theuser@hostcomment shown in the device’s authorization dialog; NULL picks a default. On success*outreceives a handle to release withadb_key_free. Seelibadb.h. - adb_
key_ ⚠private_ key_ pem - The PKCS#8 PEM private key, ready to pass to
adb_connect; NULL ifkeyis NULL. The string is owned bykeyand stays valid untiladb_key_free. - adb_
key_ ⚠public_ key - The ADB-format public key — the
adbkey.publine — ready to pass toadb_connect; NULL ifkeyis NULL. The string is owned bykeyand stays valid untiladb_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_idreceives a 64-bit channel ID for the otheradb_*_channelfunctions. Seelibadb.h. - adb_
pair ⚠pairing - Pair with a device: put the key in
priv_key_peminto its trusted store through “Pair device with pairing code” on its Wireless debugging screen (SPAKE2 inside TLS, asadb pairdoes). - adb_
read_ ⚠channel - Read from a channel into
buf(up tobuf_lenbytes). Writes the number of bytes actually read throughout_read. - adb_
reverse_ ⚠forward - Establish a reverse forward: the device listens on
device_specand opens a channel toward the host for each connection, withhost_specas its destination. Receive those channels withadb_accept_channel. - adb_
reverse_ ⚠list - List the device’s reverse rules, whichever connection established
them, as
<serial> <remote> <local>\nlines, into(buf, buf_len, out_len)peradb_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_STDINframe — no more stdin will follow. A channel the device has already closed is not a failure. Seelibadb.h. - adb_
shell_ ⚠free - Release a handle previously returned by
adb_shell_open. NULL is a no-op. The channel is not closed automatically: calladb_shell_closefirst 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. Withptythe session gets a PTY, withtermfor itsTERMandrowsandcolsfor its window size. - adb_
shell_ ⚠read_ frame - Read one decoded shell_v2 frame:
*out_idreceives the frame id,bufup tobuf_capbytes of payload and*out_lenthe full payload length. Channel closure isAdbStatus::ChannelClosed. Seelibadb.h. - adb_
shell_ ⚠set_ window_ size - Send a
WINDOW_SIZE_CHANGEframe. - adb_
shell_ ⚠write_ stdin - Send a
STDINframe. 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. Seelibadb.h. - adb_
write_ ⚠channel - Write
buf_lenbytes frombufto a channel. Returns only after all bytes have been framed and handed to the transport.
Type Aliases§
- AdbSign
Fn - C-callable signing callback,
adb_sign_fninlibadb.h.