mozdevice

https://docs.rs/mozdevice/0.5.4
Admin
A Rust library for interacting with Android devices via ADB (Android Debug Bridge) protocol.
Tokens:81,128
Snippets:706
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### starts_with

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Determines if the path starts with the given prefix. Only whole path components are considered for matching.

```APIDOC
## starts_with

### Description
Determines whether `base` is a prefix of `self`. Only considers whole path components to match.

### Method
`starts_with<P>(&self, base: P) -> bool` where P: AsRef<Path>

### Parameters
- **base** (AsRef<Path>): The path to check as a prefix.

### Response
- `bool`: `true` if the path starts with `base`, `false` otherwise.
```

--------------------------------

### Launch Android Application

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Launches an Android application with specified package and activity. Supports additional arguments for `am start` command, escaping them appropriately.

```rust
pub fn launch<T: AsRef<str>>(
        &self,
        package: &str,
        activity: &str,
        am_start_args: &[T],
    ) -> Result<bool> {
        let mut am_start = format!("am start -W -n {}/{}", package, activity);

        for arg in am_start_args {
            am_start.push(' ');
            if SYNC_REGEX.is_match(arg.as_ref()) {
                am_start.push_str(&format!("\"{}\"", &shell::escape(arg.as_ref())));
            } else {
                am_start.push_str(&shell::escape(arg.as_ref()));
            };
        }

        self.execute_host_shell_command(&am_start)
            .map(|v| v.contains("Complete"))
    }
```

--------------------------------

### Execute Host Command with Output Options

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Executes a command on the host device, with options to capture output and length. It handles communication setup and response parsing.

```rust
pub fn execute_host_command(
        &self,
        command: &str,
        has_output: bool,
        has_length: bool,
    ) -> Result<String> {
        let mut stream = self.host.connect()?;

        let switch_command = format!("host:transport:{}", self.serial);
        trace!("execute_host_command: >> {:?}", &switch_command);
        stream.write_all(encode_message(&switch_command)?.as_bytes())?;
        let _bytes = read_response(&mut stream, false, false)?;
        trace!("execute_host_command: << {:?}", _bytes);
        // TODO: should we assert no bytes were read?

        trace!("execute_host_command: >> {:?}", &command);
        stream.write_all(encode_message(command)?.as_bytes())?;
        let bytes = read_response(&mut stream, has_output, has_length)?;
        let response = std::str::from_utf8(&bytes)?;
        trace!("execute_host_command: << {:?}", response);

        // Unify new lines by removing possible carriage returns
        Ok(response.replace("\r\n", "\n"))
    }
```

--------------------------------

### Get Host Features

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Host.html

Retrieves a list of features supported by the ADB host.

```rust
pub fn features<B: FromIterator<String>>(&self) -> Result<B>
```

--------------------------------

### Device::is_app_installed

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Checks if a given application package is installed on the device.

```rust
pub fn is_app_installed(&self, package: &str) -> Result<bool>
```

--------------------------------

### is_app_installed

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Checks if a given application package is installed on the device.

```APIDOC
## is_app_installed

### Description
Checks if a specified application package is currently installed on the connected Android device.

### Method
`is_app_installed(&self, package: &str) -> Result<bool>`

### Parameters
- `package` (str): The package name of the application to check (e.g., "com.android.settings").

### Returns
- `Result<bool>`: A Result containing `true` if the app is installed, `false` otherwise. Errors during the check are propagated.
```

--------------------------------

### Device::is_app_installed

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Checks if a specific application package is installed on the device.

```APIDOC
### `Device::is_app_installed`

`pub fn is_app_installed(&self, package: &str) -> Result<bool>`

Checks if a specific application package is installed on the device.
```

--------------------------------

### Get Device Features

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Retrieves a comma-separated list of features supported by the device and parses them into an iterator of strings.

```rust
pub fn features<B: FromIterator<String>>(&self) -> Result<B> {
        let features = self.execute_host_command("features", true, true)?;
        Ok(features.split(',').map(|x| x.to_owned()).collect())
    }
```

--------------------------------

### Create a new empty String

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Use String::new() to create an empty String without initial allocation. This is efficient for starting but may lead to reallocations later.

```rust
let s = String::new();
```

--------------------------------

### Get Type ID

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/enum.SyncCommand.html

Gets the `TypeId` of the current type. This is used for dynamic trait casting.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Initialize Device

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Creates a new Device instance, setting up initial properties and checking for root access. It attempts to set the device to permissive mode if rooted.

```rust
pub fn new(host: Host, serial: DeviceSerial, storage: AndroidStorageInput) -> Result<Device> {
        let mut device = Device {
            host,
            serial,
            adbd_root: false,
            is_rooted: false,
            run_as_package: None,
            storage: AndroidStorage::App,
            su_c_root: false,
            su_0_root: false,
            tempfile: UnixPathBuf::from("/data/local/tmp"),
        };
        device
            .tempfile
            .push(Uuid::new_v4().as_hyphenated().to_string());

        // check for rooted devices
        let uid_check = |id: String| id.contains("uid=0");
        device.adbd_root = device.execute_host_shell_command("id").is_ok_and(uid_check);
        device.su_0_root = device
            .execute_host_shell_command("su 0 id")
            .is_ok_and(uid_check);
        device.su_c_root = device
            .execute_host_shell_command("su -c id")
            .is_ok_and(uid_check);
        device.is_rooted = device.adbd_root || device.su_0_root || device.su_c_root;

        device.storage = match storage {
            AndroidStorageInput::App => AndroidStorage::App,
            AndroidStorageInput::Internal => AndroidStorage::Internal,
            AndroidStorageInput::Sdcard => AndroidStorage::Sdcard,
            AndroidStorageInput::Auto => AndroidStorage::Sdcard,
        };

        if device.is_rooted {
            info!("Device is rooted");

            // Set Permissive=1 if we have root.
            device.execute_host_shell_command("setenforce permissive")?;
        } else {
            info!("Device is unrooted");
        }

        Ok(device)
    }
```

--------------------------------

### Device::new

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Constructor for creating a new Device instance.

```APIDOC
### `Device::new`

`pub fn new( host: Host, serial: DeviceSerial, storage: AndroidStorageInput, ) -> Result<Device>`

Constructor for creating a new Device instance.
```

--------------------------------

### Device::new Constructor

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Creates a new Device instance. Requires host, serial, and storage configuration.

```rust
pub fn new( host: Host,
 serial: DeviceSerial,
 storage: AndroidStorageInput,
 ) -> Result<Device>
```

--------------------------------

### Create Directory

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Creates a directory at the specified path on the device. It handles enabling 'run-as' if necessary for the given path.

```rust
pub fn create_dir(&self, path: &UnixPath) -> Result<()> {
        debug!("Creating {}", path.display());

        let enable_run_as = self.enable_run_as_for_path(path);
        self.execute_host_shell_command_as(&format!("mkdir -p {}", path.display()), enable_run_as)?;

        Ok(())
    }
```

--------------------------------

### String Capacity Management with reserve and shrink_to

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Demonstrates how to manage the allocated capacity of a String using `reserve` to ensure sufficient space and `shrink_to` to reduce it.

```rust
let mut s = String::from("foo");

s.reserve(100);
assert!(s.capacity() >= 100);

s.shrink_to(10);
assert!(s.capacity() >= 10);
s.shrink_to(0);
assert!(s.capacity() >= 3);
```

--------------------------------

### has_root

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPathBuf.html

Returns `true` if the `Path` has a root component (starts with '/').

```APIDOC
## pub fn has_root(&self) -> bool

### Description
Returns `true` if the `Path` has a root.
A path has a root if it begins with `/`.

### Returns
- **bool** - `true` if the path has a root, `false` otherwise.
```

--------------------------------

### connect

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Host.html

Establishes a TCP connection to the ADB host.

```APIDOC
## connect

Establishes a TCP connection to the ADB host.

### Returns

*   `Result<TcpStream>` - A Result containing the TcpStream or an error.
```

--------------------------------

### Connect to Host

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Host.html

Establishes a TCP connection to the ADB host.

```rust
pub fn connect(&self) -> Result<TcpStream>
```

--------------------------------

### Get SyncCommand Code

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/enum.SyncCommand.html

Retrieves the 4-byte code associated with each SyncCommand variant.

```rust
pub fn code(&self) -> &'static [u8; 4]
```

--------------------------------

### Check if UnixPath is Absolute

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Determines if a UnixPath is absolute (starts with the root). This is equivalent to checking if it has a root.

```rust
use unix_path::Path;

assert!(!Path::new("foo.txt").is_absolute());
```

--------------------------------

### String Construction from Various Types

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Demonstrates how to construct a String from different types like &String, &mut str, &str, Box<str>, Cow<'a, str>, Uuid, char, and iterators.

```APIDOC
## String Construction

### From &String
#### fn from(s: &String) -> String
Converts a `&String` into a `String` by cloning `s`.

### From &mut str
#### fn from(s: &mut str) -> String
Converts a `&mut str` into a `String`. The result is allocated on the heap.

### From &str
#### fn from(s: &str) -> String
Converts a `&str` into a `String`. The result is allocated on the heap.

### From Box<str>
#### fn from(s: Box<str>) -> String
Converts the given boxed `str` slice to a `String`. The `str` slice is owned.
##### §Examples
```rust
let s1: String = String::from("hello world");
let s2: Box<str> = s1.into_boxed_str();
let s3: String = String::from(s2);

assert_eq!("hello world", s3)
```

### From Cow<'a, str>
#### fn from(s: Cow<'a, str>) -> String
Converts a clone-on-write string to an owned instance of `String`. It clones the string if it is not already owned.
##### §Example
```rust
// If the string is not owned...
let cow: Cow<'_, str> = Cow::Borrowed("eggplant");
// It will allocate on the heap and copy the string.
let owned: String = String::from(cow);
assert_eq!(&owned[..], "eggplant");
```

### From Uuid
#### fn from(uuid: Uuid) -> String
Converts to this type from the input type.

### From char
#### fn from(c: char) -> String
Allocates an owned `String` from a single character.
##### §Example
```rust
let c: char = 'a';
let s: String = String::from(c);
assert_eq!("a", &s[..]);
```

### From Iterators
#### fn from_iter<I>(iter: I) -> String
where I: IntoIterator<Item = &'a char>,
Creates a value from an iterator of characters.

#### fn from_iter<I>(iter: I) -> String
where I: IntoIterator<Item = &'a str>,
Creates a value from an iterator of string slices.

#### fn from_iter<I>(iter: I) -> String
where I: IntoIterator<Item = Box<str, A>>,
Creates a value from an iterator of boxed string slices.

#### fn from_iter<I>(iter: I) -> String
where I: IntoIterator<Item = Cow<'a, str>>,
Creates a value from an iterator of clone-on-write strings.

#### fn from_iter<I>(iter: I) -> String
where I: IntoIterator<Item = String>,
Creates a value from an iterator of Strings.

#### fn from_iter<I>(iter: I) -> String
where I: IntoIterator<Item = char>,
Creates a value from an iterator of characters.
```

--------------------------------

### Getting String Slice

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Extracts an immutable string slice (`&str`) representing the entire content of the String.

```rust
let s = String::from("foo");

assert_eq!("foo", s.as_str());
```

--------------------------------

### Device::launch

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Launches an application activity on the device with specified arguments.

```rust
pub fn launch<T: AsRef<str>>( 
 &self,
 package: &str,
 activity: &str,
 am_start_args: &[T],
 ) -> Result<bool>
```

--------------------------------

### Implement ADB Sync Protocol for Listing Directory

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Implements the ADB sync protocol to list directory contents. This involves connecting to the device, sending 'host:transport' and 'sync:' commands, followed by a 'LIST' command with the directory path.

```rust
fn list_dir_flat(
        &self,
        src: &UnixPath,
        depth: usize,
        prefix: String,
    ) -> Result<Vec<RemoteDirEntry>> {
        // Implement the ADB protocol to list a directory from the device.
        let mut stream = self.host.connect()?;

        // Send "host:transport" command with device serial
        let message = encode_message(&format!("host:transport:{}", self.serial))?;
        stream.write_all(message.as_bytes())?;
        let _bytes = read_response(&mut stream, false, true)?;

        // Send "sync:" command to initialize file transfer
        let message = encode_message("sync:")?;
        stream.write_all(message.as_bytes())?;
        let _bytes = read_response(&mut stream, false, true)?;

        // Send "LIST" command with name of the directory
        stream.write_all(SyncCommand::List.code())?;
        let args_ = format!("{}", src.display());
        let args = args_.as_bytes();
        write_length_little_endian(&mut stream, args.len())?;
        stream.write_all(args)?;

        // Use the maximum 64KB buffer to transfer the file contents.
        let mut buf = [0; 64 * 1024];

        let mut listings = Vec::new();

        // Read "DENT" command one or more times for the directory entries

```

--------------------------------

### Get Parent of UnixPath

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Retrieves the parent directory of a UnixPath. Returns None if the path terminates at the root.

```rust
use unix_path::Path;

let path = Path::new("/foo/bar");
let parent = path.parent().unwrap();
assert_eq!(parent, Path::new("/foo"));

let grand_parent = parent.parent().unwrap();
assert_eq!(grand_parent, Path::new("/"));
assert_eq!(grand_parent.parent(), None);
```

--------------------------------

### Device::create_dir

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Creates a directory on the device at the specified path.

```rust
pub fn create_dir(&self, path: &UnixPath) -> Result<()>
```

--------------------------------

### Get String Capacity

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Returns the current capacity of the String in bytes. Use this to check how much memory is allocated.

```rust
let s = String::with_capacity(10);

assert!(s.capacity() >= 10);
```

--------------------------------

### Launch Application

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Launches an application on the device with specified package, activity, and arguments.

```APIDOC
## launch

### Description
Launches an application on the device.

### Signature
pub fn launch<T: AsRef<str>>(
    &self,
    package: &str,
    activity: &str,
    am_start_args: &[T],
) -> Result<bool>

### Parameters
- `package` (str): The package name of the application.
- `activity` (str): The activity name to launch.
- `am_start_args` (&[T]): Additional arguments for the `am start` command.

### Returns
- `Result<bool>`: Ok(true) if the launch was successful and indicated by 'Complete' in the output, Ok(false) otherwise.
```

--------------------------------

### report(self)

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/type.Result.html

Is called to get the representation of the value as status code. This status code is returned to the operating system.

```APIDOC
## fn report(self) -> ExitCode

### Description
Is called to get the representation of the value as status code. This status code is returned to the operating system.
```

--------------------------------

### Create UnixPath from String and Path

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Illustrates creating UnixPath instances from owned Strings and existing Path slices. The conversion is a no-op.

```rust
use unix_path::Path;

let string = String::from("foo.txt");
let from_string = Path::new(&string);
let from_path = Path::new(&from_string);
assert_eq!(from_string, from_path);
```

--------------------------------

### Get String Length in Bytes

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Returns the length of the String in bytes. Note that this may not correspond to the number of characters or graphemes.

```rust
let a = String::from("foo");
assert_eq!(a.len(), 3);

let fancy_f = String::from("ƒoo");
assert_eq!(fancy_f.len(), 4);
assert_eq!(fancy_f.chars().count(), 3);
```

--------------------------------

### Get File Name with UnixPath

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Retrieves the final component of a Unix path. Returns None if the path terminates in '..'.

```rust
use unix_path::Path;
use unix_str::UnixStr;

assert_eq!(Some(UnixStr::new("bin")), Path::new("/usr/bin/").file_name());
assert_eq!(Some(UnixStr::new("foo.txt")), Path::new("tmp/foo.txt").file_name());
assert_eq!(Some(UnixStr::new("foo.txt")), Path::new("foo.txt/.").file_name());
assert_eq!(Some(UnixStr::new("foo.txt")), Path::new("foo.txt/.//").file_name());
assert_eq!(None, Path::new("foo.txt/..").file_name());
assert_eq!(None, Path::new("/").file_name());
```

--------------------------------

### Device::launch

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Launches an application activity on the device.

```APIDOC
### `Device::launch`

`pub fn launch<T: AsRef<str>>( &self, package: &str, activity: &str, am_start_args: &[T], ) -> Result<bool>`

Launches an application activity on the device.
```

--------------------------------

### Get Underlying UnixStr from UnixPath

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Retrieves the underlying UnixStr slice from a UnixPath. This provides access to the raw path bytes.

```rust
use unix_path::Path;
use unix_str::UnixStr;

let os_str = Path::new("foo.txt").as_unix_str();
assert_eq!(os_str, UnixStr::new("foo.txt"));
```

--------------------------------

### is_absolute

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPathBuf.html

Returns `true` if the `Path` is absolute, meaning it is independent of the current directory. A path is considered absolute if it starts with the root.

```APIDOC
## pub fn is_absolute(&self) -> bool

### Description
Returns `true` if the `Path` is absolute, i.e., if it is independent of the current directory.
A path is absolute if it starts with the root, so `is_absolute` and `has_root` are equivalent.

### Returns
- **bool** - `true` if the path is absolute, `false` otherwise.
```

--------------------------------

### Device::execute_host_shell_command_as

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Executes a shell command on the device, with an option to enable 'run-as'.

```rust
pub fn execute_host_shell_command_as(
 &self,
 shell_command: &str,
 enable_run_as: bool,
 ) -> Result<String>
```

--------------------------------

### Device::execute_host_shell_command_as

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Executes a shell command on the device, with an option to enable 'run-as'.

```APIDOC
### `Device::execute_host_shell_command_as`

`pub fn execute_host_shell_command_as( &self, shell_command: &str, enable_run_as: bool, ) -> Result<String>`

Executes a shell command on the device, with an option to enable 'run-as'.
```

--------------------------------

### Getting a byte slice representation of a String

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Illustrates how to obtain a byte slice (`&[u8]`) from a String's contents using `as_bytes`.

```rust
let s = String::from("hello");

assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes());
```

--------------------------------

### Getting Mutable String Slice

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Converts a mutable `String` into a mutable string slice (`&mut str`), allowing in-place modifications.

```rust
let mut s = String::from("foobar");
let s_mut_str = s.as_mut_str();

s_mut_str.make_ascii_uppercase();

assert_eq!("FOOBAR", s_mut_str);
```

--------------------------------

### Default String Creation

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Shows how to create an empty String using its default implementation.

```APIDOC
## fn default() -> String

### Description
Creates an empty `String`.

### Returns
An empty `String` instance.
```

--------------------------------

### Iterate Over Path Components

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Use `components()` to get an iterator over the `Component`s of a path. Normalization rules apply to separators, '.', and trailing slashes.

```rust
use unix_path::{Path, Component};
use unix_str::UnixStr;

let mut components = Path::new("/tmp/foo.txt").components();

assert_eq!(components.next(), Some(Component::RootDir));
assert_eq!(components.next(), Some(Component::Normal(UnixStr::new("tmp"))));
assert_eq!(components.next(), Some(Component::Normal(UnixStr::new("foo.txt"))));
assert_eq!(components.next(), None)
```

--------------------------------

### String Indexing and Ordering

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Explains how to index into a String mutably and immutably, and how String comparison works.

```APIDOC
### String Indexing

#### type Output = <I as SliceIndex<str>>::Output
The returned type after indexing.

#### fn index(&self, index: I) -> &<I as SliceIndex<str>>::Output
Performs the indexing (`container[index]`) operation.

#### fn index_mut(&mut self, index: I) -> &mut <I as SliceIndex<str>>::Output
Performs the mutable indexing (`container[index]`) operation.

### String Ordering

#### fn cmp(&self, other: &String) -> Ordering
This method returns an `Ordering` between `self` and `other`.

#### fn max(self, other: Self) -> Self
where Self: Sized,
Compares and returns the maximum of two values.

#### fn min(self, other: Self) -> Self
where Self: Sized,
Compares and returns the minimum of two values.

#### fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,
Restrict a value to a certain interval.
```

--------------------------------

### Connect to ADB Host

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Establishes a TCP connection to the ADB host with configured timeouts. Defaults to localhost:5037 if host or port are not specified.

```rust
pub fn connect(&self) -> Result<TcpStream> {
    let stream = TcpStream::connect(format!(
        "{}:{}",
        self.host.clone().unwrap_or_else(|| "localhost".to_owned()),
        self.port.unwrap_or(5037)
    ))?;
    stream.set_read_timeout(self.read_timeout)?;
    stream.set_write_timeout(self.write_timeout)?;
    Ok(stream)
}
```

--------------------------------

### Building a PathBuf with push and set_extension

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPathBuf.html

Use `push` to dynamically build a PathBuf by appending components. `set_extension` can be used to add or modify the file extension.

```rust
use unix_path::PathBuf;

let mut path = PathBuf::new();

path.push("/");
path.push("feel");
path.push("the");

path.set_extension("force");
```

--------------------------------

### Coercing PathBuf to a Path slice

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPathBuf.html

The `as_path` method allows you to get a reference to the underlying `Path` slice, enabling the use of `Path` methods on a `PathBuf`.

```rust
use unix_path::{Path, PathBuf};

let p = PathBuf::from("/test");
assert_eq!(Path::new("/test"), p.as_path());
```

--------------------------------

### UnixPath::is_absolute

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Returns `true` if the `Path` is absolute, i.e., if it is independent of the current directory. A path is absolute if it starts with the root, so `is_absolute` and `has_root` are equivalent.

```APIDOC
## UnixPath::is_absolute

### Description
Returns `true` if the `Path` is absolute, i.e., if it is independent of the current directory. A path is absolute if it starts with the root, so `is_absolute` and `has_root` are equivalent.

### Method
`pub fn is_absolute(&self) -> bool`

### Examples
```
use unix_path::Path;

assert!(!Path::new("foo.txt").is_absolute());
```
```

--------------------------------

### Device::enable_run_as_for_path

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Enables the 'run-as' functionality for a specific path on the device.

```rust
pub fn enable_run_as_for_path(&self, path: &UnixPath) -> bool
```

--------------------------------

### Getting the capacity of a PathBuf

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPathBuf.html

The `capacity` method returns the current allocated capacity of the internal `UnixString` buffer, indicating how many bytes can be stored without reallocating.

```rust
use unix_path::PathBuf;

let path = PathBuf::from("/some/path");
let capacity = path.capacity();
```

--------------------------------

### Create UnixPath from String Slice

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Shows how to create a UnixPath directly from a string slice. This is a cost-free conversion.

```rust
use unix_path::Path;

Path::new("foo.txt");
```

--------------------------------

### Device selection and connection

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

The `device_or_default` method allows searching for available devices and selecting a specific one using a serial number or falling back to environment variables or the only available device. It returns a `Device` object for the selected device.

```APIDOC
impl Host {
    /// Searches for available devices, and selects the one as specified by `device_serial`.
    ///
    /// If multiple devices are online, and no device has been specified,
    /// the `ANDROID_SERIAL` environment variable can be used to select one.
    pub fn device_or_default<T: AsRef<str>>(
        self,
        device_serial: Option<&T>,
        storage: AndroidStorageInput,
    ) -> Result<Device> {
        let serials: Vec<String> = self
            .devices::<Vec<_>>()? // Assuming `devices` method exists and returns device info
            .into_iter()
            .map(|d| d.serial) // Assuming device info has a `serial` field
            .collect();

        if let Some(ref serial) = device_serial
            .map(|v| v.as_ref().to_owned())
            .or_else(|| std::env::var("ANDROID_SERIAL").ok())
        {
            if !serials.contains(serial) {
                return Err(DeviceError::UnknownDevice(serial.clone()));
            }

            return Device::new(self, serial.to_owned(), storage); // Assuming `Device::new` exists
        }

        if serials.len() > 1 {
            return Err(DeviceError::MultipleDevices);
        }

        if let Some(ref serial) = serials.first() {
            return Device::new(self, serial.to_owned().to_string(), storage);
        }

        Err(DeviceError::Adb("No Android devices are online".to_owned()))
    }
}
```

--------------------------------

### Extract File Extension from UnixPath

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Extracts the extension of the file name. Returns None if there is no file name, no extension, or if the file name starts with a dot and has no other dots.

```rust
use unix_path::Path;
use unix_str::UnixStr;

let path = Path::new("foo.rs");

assert_eq!(UnixStr::new("rs"), path.extension().unwrap());
```

--------------------------------

### Device::create_dir

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Creates a directory on the device at the specified path.

```APIDOC
### `Device::create_dir`

`pub fn create_dir(&self, path: &UnixPath) -> Result<()>`

Creates a directory on the device at the specified path.
```

--------------------------------

### Default Host Implementation

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Host.html

Provides a default Host configuration, typically connecting to localhost on port 5037 with 2-second timeouts.

```rust
fn default() -> Host
```

--------------------------------

### Get Mutable Reference to Value

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/type.Result.html

The `as_mut()` method converts a `&mut Result<T, E>` into a `Result<&mut T, &mut E>`. This allows modifying the contained value in place.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Device::enable_run_as_for_path

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Enables the 'run-as' feature for a specific path on the device.

```APIDOC
### `Device::enable_run_as_for_path`

`pub fn enable_run_as_for_path(&self, path: &UnixPath) -> bool`

Enables the 'run-as' feature for a specific path on the device.
```

--------------------------------

### Get Reference to Ok Value

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/type.Result.html

The `as_ref()` method converts a `&Result<T, E>` into a `Result<&T, &E>`. This allows borrowing the contained value without consuming the original `Result`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Execute Host Shell Command with Run As Option

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Executes a shell command on the host, with an option to enable 'run-as' for specific packages. It handles different privilege escalation methods (su, adbd root, run-as) and quoting.

```rust
pub fn execute_host_shell_command_as(
        &self,
        shell_command: &str,
        enable_run_as: bool,
    ) -> Result<String> {
        // We don't want to duplicate su invocations.
        if shell_command.starts_with("su") {
            return self.execute_host_command(&format!("shell:{}", shell_command), true, false);
        }

        let has_outer_quotes = shell_command.starts_with('"') && shell_command.ends_with('"')
            || shell_command.starts_with('\'') && shell_command.ends_with('\'');

        if self.adbd_root {
            return self.execute_host_command(&format!("shell:{}", shell_command), true, false);
        }

        if self.su_0_root {
            return self.execute_host_command(
                &format!("shell:su 0 {}", shell_command),
                true,
                false,
            );
        }

        if self.su_c_root {
            if has_outer_quotes {
                return self.execute_host_command(
                    &format!("shell:su -c {}", shell_command),
                    true,
                    false,
                );
            }

            if SYNC_REGEX.is_match(shell_command) {
                let arg: &str = &shell_command.replace('\'','\'"'"'\'')[..];
                return self.execute_host_command(&format!("shell:su -c '{}'", arg), true, false);
            }

            return self.execute_host_command(
                &format!("shell:su -c \"{}\"", shell_command),
                true,
                false,
            );
        }

        // Execute command as package
        if enable_run_as {
            let run_as_package = self
                .run_as_package
                .as_ref()
                .ok_or(DeviceError::MissingPackage)?;

            if has_outer_quotes {
                return self.execute_host_command(
                    &format!("shell:run-as {} {}", run_as_package, shell_command),
                    true,
                    false,
                );
            }

            if SYNC_REGEX.is_match(shell_command) {
                let arg: &str = &shell_command.replace('\'','\'"'"'\'')[..];
                return self.execute_host_command(
                    &format!("shell:run-as {} {}", run_as_package, arg),
                    true,
                    false,
                );
            }

            return self.execute_host_command(
                &format!("shell:run-as {} \"{}\"", run_as_package, shell_command),
                true,
                false,
            );
        }

        self.execute_host_command(&format!("shell:{}", shell_command), true, false)
    }
```

--------------------------------

### Push File with Sync Protocol

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Handles the ADB SYNC protocol for pushing a file to a device. It sends file data, a 'DONE' command with a timestamp, and expects an 'OKAY' or 'FAIL' response. Includes logic for `run_as` mode and error handling.

```rust
            write_length_little_endian(&mut stream, len)?;
            stream.write_all(&buf[0..len])?;
        }

        // https://android.googlesource.com/platform/system/core/+/master/adb/SYNC.TXT#66
        //
        // When the file is transferred a sync request "DONE" is sent, where length is set
        // to the last modified time for the file. The server responds to this last
        // request (but not to chunk requests) with an "OKAY" sync response (length can
        // be ignored).
        let time: u32 = ((SystemTime::now().duration_since(SystemTime::UNIX_EPOCH))
            .unwrap()
            .as_secs()
            & 0xFFFF_FFFF) as u32;

        stream.write_all(SyncCommand::Done.code())?;
        write_length_little_endian(&mut stream, time as usize)?;

        // Status.
        stream.read_exact(&mut buf[0..4])?;

        if buf.starts_with(SyncCommand::Okay.code()) {
            if enable_run_as {
                // Use cp -a to preserve the permissions set by push.
                let result = self.execute_host_shell_command_as(
                    format!("cp -aR {} {}", dest1.display(), dest.display()).as_str(),
                    enable_run_as,
                );
                if self.remove(dest1).is_err() {
                    warn!("Failed to remove {}", dest1.display());
                }
                result?;
            }
            Ok(())
        } else if buf.starts_with(SyncCommand::Fail.code()) {
            if enable_run_as && self.remove(dest1).is_err() {
                warn!("Failed to remove {}", dest1.display());
            }
            let n = buf.len().min(read_length_little_endian(&mut stream)?);

            stream.read_exact(&mut buf[0..n])?;

            let message = std::str::from_utf8(&buf[0..n])
                .map(|s| format!("adb error: {}", s))
                .unwrap_or_else(|_| "adb error was not utf-8".into());

            Err(DeviceError::Adb(message))
        } else {
            if self.remove(dest1).is_err() {
                warn!("Failed to remove {}", dest1.display());
            }
            Err(DeviceError::Adb("FAIL (unknown)".to_owned()))
        }
```

--------------------------------

### Iterate Over Path Components as UnixStr Slices

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Use `iter()` to get an iterator over the path's components as `UnixStr` slices. This method follows the same component separation rules as `components()`.

```rust
use unix_path::{self, Path};
use unix_str::UnixStr;

let mut it = Path::new("/tmp/foo.txt").iter();
assert_eq!(it.next(), Some(UnixStr::new("/")));
assert_eq!(it.next(), Some(UnixStr::new("tmp")));
assert_eq!(it.next(), Some(UnixStr::new("foo.txt")));
assert_eq!(it.next(), None)
```

--------------------------------

### Collect into Result with Checked Subtraction (Underflow)

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/type.Result.html

Illustrates how `collect` stops at the first `Err` when processing an iterator. This example shows an underflow error, causing the collection to fail and return the error.

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| 
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

--------------------------------

### List Available Devices

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Host.html

Retrieves a list of connected ADB devices.

```rust
pub fn devices<B: FromIterator<DeviceInfo>>(&self) -> Result<B>
```

--------------------------------

### into_ok

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/type.Result.html

Returns the contained Ok value, but never panics. This is a nightly-only experimental API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. This method is known to never panic on the result types it is implemented for, making it a maintainability safeguard.

### Method
`into_ok()`

### Constraints
Requires `E: Into<!>`.

### Note
This is a nightly-only experimental API.

### Example
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```
```

--------------------------------

### Select ADB Device or Default

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Selects a specific ADB device by serial number or environment variable, or the default device if only one is available. Returns an error if no devices are found or the specified device is unknown.

```rust
pub fn device_or_default<T: AsRef<str>>(
    self,
    device_serial: Option<&T>,
    storage: AndroidStorageInput,
) -> Result<Device> {
    let serials: Vec<String> = self
        .devices::<Vec<_>>()?
        .into_iter()
        .map(|d| d.serial)
        .collect();

    if let Some(ref serial) = device_serial
        .map(|v| v.as_ref().to_owned())
        .or_else(|| std::env::var("ANDROID_SERIAL").ok())
    {
        if !serials.contains(serial) {
            return Err(DeviceError::UnknownDevice(serial.clone()));
        }

        return Device::new(self, serial.to_owned(), storage);
    }

    if serials.len() > 1 {
        return Err(DeviceError::MultipleDevices);
    }

    if let Some(ref serial) = serials.first() {
        return Device::new(self, serial.to_owned().to_string(), storage);
    }

    Err(DeviceError::Adb("No Android devices are online".to_owned()))
}
```

--------------------------------

### Device::push_dir

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Pushes an entire directory from the local system to the device with specified mode.

```rust
pub fn push_dir(
 &self,
 source: &Path,
 dest_dir: &UnixPath,
 mode: u32,
 ) -> Result<()>
```

--------------------------------

### String Formatting

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/adb/type.DeviceSerial.html

Demonstrates how to format a String value using a given formatter.

```APIDOC
## fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

### Description
Formats the value using the given formatter.

### Parameters
- `f`: A mutable reference to a `Formatter` object.

### Returns
A `Result` indicating success or failure of the formatting operation.
```

--------------------------------

### Execute Host Command

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Host.html

Executes a command on the ADB host, with options to indicate if output and length are expected.

```rust
pub fn execute_host_command(
    &self,
    host_command: &str,
    has_length: bool,
    has_output: bool,
) -> Result<String>
```

--------------------------------

### CloneToUninit Trait Implementation (Nightly)

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPathBuf.html

Experimental nightly-only API for cloning data to uninitialized memory.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

Performs copy-assignment from `self` to `dest`.
```

--------------------------------

### Initializing an empty PathBuf

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPathBuf.html

Use `PathBuf::new()` to allocate an empty PathBuf. This is useful when the path will be built dynamically.

```rust
use unix_path::PathBuf;

let path = PathBuf::new();
```

--------------------------------

### execute_command

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Host.html

Executes a command on the ADB host and returns its output.

```APIDOC
## execute_command

Executes a command on the ADB host.

### Parameters

*   `command: &str` - The command to execute.
*   `has_output: bool` - Whether the command is expected to produce output.
*   `has_length: bool` - Whether the output length is included.

### Returns

*   `Result<String>` - A Result containing the command output as a String or an error.
```

--------------------------------

### Device::list_dir

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Lists the entries in a directory on the device.

```rust
pub fn list_dir(&self, src: &UnixPath) -> Result<Vec<RemoteDirEntry>>
```

--------------------------------

### with_extension

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.UnixPath.html

Creates a new owned `PathBuf` with the extension component replaced by the given new extension.

```APIDOC
## with_extension

### Description
Creates an owned `PathBuf` like `self` but with the given extension. See `PathBuf::set_extension` for more details.

### Method
`with_extension<S>(&self, extension: S) -> PathBuf` where S: AsRef<UnixStr>

### Parameters
- **extension** (AsRef<UnixStr>): The new extension to set.

### Response
- `PathBuf`: An owned `PathBuf` with the updated extension.
```

--------------------------------

### push_dir

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

Recursively pushes a directory from the host to a specified directory on the device. It iterates through the source directory, pushing each file individually using the `push` method.

```APIDOC
## push_dir

### Description
Recursively pushes a directory from the host to a specified directory on the device. It walks the source directory and pushes each file found.

### Method
(Implicitly part of the Device struct methods)

### Parameters
- `source`: A reference to the source directory path on the host.
- `dest_dir`: The destination directory path on the device as a `UnixPath`.
- `mode`: The file mode (permissions) to set on the pushed files.

### Request Example
(Code example not provided in source)

### Response
- `Ok(())`: If the directory is successfully pushed.
- `Err(io::Error)`: If any I/O error occurs during directory traversal or file pushing.

#### Success Response (200)
(Implicit success, no explicit response structure defined)

#### Response Example
(No explicit response example provided in source)
```

--------------------------------

### Device::execute_host_shell_command

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Executes a shell command on the device and returns the output.

```rust
pub fn execute_host_shell_command(&self, shell_command: &str) -> Result<String>
```

--------------------------------

### Device::execute_host_command

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Executes a command on the ADB host and returns its output if requested.

```rust
pub fn execute_host_command(
 &self,
 command: &str,
 has_output: bool,
 has_length: bool,
 ) -> Result<String>
```

--------------------------------

### Establishing TCP connection

Source: https://docs.rs/mozdevice/0.5.4/src/mozdevice/lib.rs.html

The `connect` method establishes a TCP connection to the ADB host using the configured host, port, and timeouts. It returns a `TcpStream` object.

```APIDOC
impl Host {
    pub fn connect(&self) -> Result<TcpStream> {
        let stream = TcpStream::connect(format!(
            "{}:{}",
            self.host.clone().unwrap_or_else(|| "localhost".to_owned()),
            self.port.unwrap_or(5037)
        ))?;
        stream.set_read_timeout(self.read_timeout)?;
        stream.set_write_timeout(self.write_timeout)?;
        Ok(stream)
    }
}
```

--------------------------------

### Device::push_dir

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.Device.html

Pushes a local directory to the device.

```APIDOC
### `Device::push_dir`

`pub fn push_dir( &self, source: &Path, dest_dir: &UnixPath, mode: u32, ) -> Result<()>`

Pushes a local directory to the device.
```

--------------------------------

### StructuralPartialEq Implementation for DeviceInfo

Source: https://docs.rs/mozdevice/0.5.4/mozdevice/struct.DeviceInfo.html

Implements StructuralPartialEq for DeviceInfo, indicating structural equality.

```rust
impl StructuralPartialEq for DeviceInfo
```
Tokens:
Raw