Skip to main content

adb/
lib.rs

1//! C ABI for [`libadb`].
2//!
3//! The API is synchronous from the caller's perspective: each async
4//! operation is driven to completion by a tiny internal executor. No
5//! tokio or smol runtime is required.
6//!
7//! `include/libadb.h` is the contract: it says in full what each call
8//! does and returns, how it fails, what stays valid and what the caller
9//! must do. The rustdoc here gives a summary and the `# Safety` section.
10//!
11//! Under the hood a handle is a split [`Reader`] / [`Writer`] pair
12//! sharing a reference-counted state. A write never waits for the
13//! [`Reader`]'s mutex, so a thread blocked in a long read does not
14//! prevent another thread from writing — which is what makes
15//! interactive shell sessions usable from C without any async runtime.
16//!
17//! [`Reader::run`] is never started, so only a call holding the read
18//! lock takes packets off the connection, and that includes the OKAY
19//! [`Writer::write_channel`] waits for. A write waiting for the device
20//! with no read call running reads the connection itself, under that
21//! lock. A read does not wait for the lock: finding it taken, the read
22//! takes what the holder dispatches for its channel, and the lock once
23//! it comes free.
24//!
25//! # Feature flags
26//!
27//! TCP support is always compiled in and needs no async runtime. USB
28//! support is opt-in: enable `usb` (alias for the pure-Rust `nusb`
29//! backend) or `rusb` (libusb). Both may be on at once, and `usb://`
30//! then goes to `nusb`, since [`adb_connect`] cannot choose a backend.
31//!
32//! `tls` answers a wireless-debugging device's `STLS` (Android 11+)
33//! from [`adb_connect`] with TLS 1.3, presenting the caller's key in a
34//! certificate; without it such a device is [`AdbStatus::TlsRequired`].
35//! [`adb_connect_with_authenticator`] stays in the clear either way.
36//!
37//! `pairing` (implies `tls`) adds `adb_pair`, the `adb pair` exchange
38//! against the device's pairing dialog: the one way to put a key on a
39//! device that has never seen it without a USB cable.
40//!
41//! [`Reader`]: libadb::Reader
42//! [`Reader::run`]: libadb::Reader::run
43//! [`Writer`]: libadb::Writer
44//! [`Writer::write_channel`]: libadb::Writer::write_channel
45
46#![no_std]
47#![allow(unsafe_code)]
48#![warn(unsafe_op_in_unsafe_fn)]
49#![warn(missing_docs)]
50#![cfg_attr(docsrs, feature(doc_cfg))]
51
52extern crate alloc;
53extern crate std;
54
55#[macro_use]
56mod macros;
57
58mod auth;
59mod block_on;
60mod channel;
61mod connection;
62mod error;
63mod feature;
64mod incoming;
65mod keys;
66#[cfg(feature = "pairing")]
67mod pairing;
68mod reverse;
69mod shell;
70mod slice;
71mod transport;
72
73pub use auth::{adb_authenticator_t, AdbSignFn};
74pub use channel::{adb_close_channel, adb_open_channel, adb_read_channel, adb_write_channel};
75pub use connection::{
76    adb_connect, adb_connect_with_authenticator, adb_connection_delayed_ack,
77    adb_connection_device_banner, adb_connection_free, adb_connection_max_payload,
78    adb_connection_set_io_timeout_ms, adb_connection_t,
79};
80pub use error::{adb_last_error, AdbStatus};
81pub use feature::{adb_connection_features, adb_connection_has_feature, adb_feature_name};
82pub use incoming::{adb_accept_channel, adb_incoming_accept, adb_incoming_reject};
83pub use keys::{
84    adb_key_free, adb_key_load_or_generate, adb_key_private_key_pem, adb_key_public_key, adb_key_t,
85};
86#[cfg(feature = "pairing")]
87pub use pairing::adb_pair;
88pub use reverse::{
89    adb_reverse_forward, adb_reverse_list, adb_reverse_remove, adb_reverse_remove_all,
90};
91pub use shell::{
92    adb_shell_close, adb_shell_close_stdin, adb_shell_free, adb_shell_open, adb_shell_read_frame,
93    adb_shell_set_window_size, adb_shell_t, adb_shell_write_stdin,
94};