libadb-ffi 0.9.0

C ABI for libadb
Documentation
use libadb::base::channel::ChannelId;

use crate::block_on;
use crate::connection::adb_connection_t;
use crate::error::{self, AdbStatus};
use crate::slice;

pub(crate) fn encode_channel_id(ch: ChannelId) -> u64 {
    ((ch.local_id() as u64) << 32) | (ch.slot() as u32 as u64)
}

fn decode_channel_id(conn: &adb_connection_t, id: u64) -> Result<ChannelId, AdbStatus> {
    let slot = usize::try_from(id & 0xFFFF_FFFF)
        .ok()
        .filter(|&slot| slot < conn.writer.config().max_channels());
    let Some(slot) = slot else {
        return Err(error::fail_invalid_arg(
            "channel id names no slot of this connection",
        ));
    };
    Ok(ChannelId::from_raw(slot, (id >> 32) as u32))
}

/// 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`.
///
/// # Safety
/// `conn` must be a valid handle. `destination` must be NULL or point
/// to at least `destination_len` readable bytes. `out_id` must point
/// to a writable `uint64_t`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn adb_open_channel(
    conn: *mut adb_connection_t,
    destination: *const u8,
    destination_len: usize,
    out_id: *mut u64,
) -> AdbStatus {
    error::clear_last_error();
    if conn.is_null() || out_id.is_null() || (destination.is_null() && destination_len > 0) {
        return error::fail_invalid_arg("null pointer");
    }
    // SAFETY: non-null, and a valid handle per `# Safety`.
    let conn = unsafe { &*conn };
    // SAFETY: readable for `destination_len` bytes when non-null, per `# Safety`.
    let dest = unsafe { slice::from_ptr(destination, destination_len) };
    let mut g = conn.lock_reader();
    let id = ffi_try!(g.open_channel(dest));
    // SAFETY: non-null, and writable per `# Safety`.
    unsafe { *out_id = encode_channel_id(id) };
    AdbStatus::Ok
}

/// Read from a channel into `buf` (up to `buf_len` bytes). Writes the
/// number of bytes actually read through `out_read`.
///
/// `ADB_OK` with `*out_read == 0` never occurs: channel closure is
/// [`AdbStatus::ChannelClosed`]. See `libadb.h`.
///
/// # Safety
/// `conn` must be a valid handle. `buf` must be NULL or point to at
/// least `buf_len` writable bytes. `out_read` must point to a
/// writable `usize`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn adb_read_channel(
    conn: *mut adb_connection_t,
    id: u64,
    buf: *mut u8,
    buf_len: usize,
    out_read: *mut usize,
) -> AdbStatus {
    error::clear_last_error();
    if conn.is_null() || out_read.is_null() || (buf.is_null() && buf_len > 0) {
        return error::fail_invalid_arg("null pointer");
    }
    if buf_len == 0 {
        return error::fail_invalid_arg("buf_len is zero");
    }
    // SAFETY: non-null, and a valid handle per `# Safety`.
    let conn = unsafe { &*conn };
    // SAFETY: non-null, as `buf_len` is not zero, and writable for it per `# Safety`.
    let slice = unsafe { slice::from_mut_ptr(buf, buf_len) };
    let ch = match decode_channel_id(conn, id) {
        Ok(ch) => ch,
        Err(status) => return status,
    };
    let n = match block_on::block_on_read(&conn.reader, &conn.writer, ch, slice) {
        Ok(n) => n,
        Err(e) => return error::fail_error(e),
    };
    // SAFETY: non-null, and writable per `# Safety`.
    unsafe { *out_read = n };
    AdbStatus::Ok
}

/// Write `buf_len` bytes from `buf` to a channel. Returns only after
/// all bytes have been framed and handed to the transport.
///
/// With no read call running, this reads the connection itself while
/// it waits for the device. See `libadb.h`.
///
/// # Safety
/// `conn` must be a valid handle. `buf` must be NULL or point to at
/// least `buf_len` readable bytes.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn adb_write_channel(
    conn: *mut adb_connection_t,
    id: u64,
    buf: *const u8,
    buf_len: usize,
) -> AdbStatus {
    error::clear_last_error();
    if conn.is_null() || (buf.is_null() && buf_len > 0) {
        return error::fail_invalid_arg("null pointer");
    }
    // SAFETY: non-null, and a valid handle per `# Safety`.
    let conn = unsafe { &*conn };
    // SAFETY: readable for `buf_len` bytes when non-null, per `# Safety`.
    let slice = unsafe { slice::from_ptr(buf, buf_len) };
    let ch = match decode_channel_id(conn, id) {
        Ok(ch) => ch,
        Err(status) => return status,
    };
    let write = conn.writer.write_channel(ch, slice);
    if let Err(e) = block_on::block_on_write(&conn.reader, &conn.writer, ch, write) {
        return error::fail_error(e);
    }
    AdbStatus::Ok
}

/// Close a channel. Subsequent reads/writes against this ID will fail
/// with [`AdbStatus::ChannelClosed`]. See `libadb.h`.
///
/// # Safety
/// `conn` must be a valid handle.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn adb_close_channel(conn: *mut adb_connection_t, id: u64) -> AdbStatus {
    error::clear_last_error();
    if conn.is_null() {
        return error::fail_invalid_arg("null handle");
    }
    // SAFETY: non-null, and a valid handle per `# Safety`.
    let conn = unsafe { &*conn };
    let ch = match decode_channel_id(conn, id) {
        Ok(ch) => ch,
        Err(status) => return status,
    };
    ffi_try!(conn.writer.close_channel(ch));
    AdbStatus::Ok
}