# hdc_lib_rs

**Repository Path**: Cooper0/hdc_lib_rs

## Basic Information

- **Project Name**: hdc_lib_rs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HDC Lib RS

[English](README_EN.md) | 中文

## 项目概述

HDC Lib RS 是一个使用 Rust 对 OpenHarmony HDC (OpenHarmony Device Connector) 工具进行封装的库。它提供了便捷的 API 接口，用于与 OpenHarmony 设备进行交互和调试。

本项目通过将 HDC 二进制文件打包到库中，并智能检测系统环境，确保在没有安装 HDC 的环境下也能正常工作。

## 功能特性

### 核心功能

- **智能 HDC 检测**：自动检测系统是否安装 HDC，优先使用系统版本
- **内置 HDC 二进制**：打包 HDC 工具，无依赖环境下也能运行
- **泛型命令接口**：支持任意 HDC 命令调用
- **设备管理接口**：提供设备列表查询、日志清理等常用功能

### 特性列表

- 使用 `include_bytes!` 将 HDC 二进制打包，支持多平台资源隔离
- 自动检测系统 HDC 安装状态
- 未安装时自动提取内置 HDC 到可执行程序同级目录
- 泛型命令执行接口，支持迭代器参数
- 命令行参数透传示例

## 技术栈

- **语言**：Rust (Edition 2024)
- **构建系统**：Cargo
- **依赖库**：
  - anyhow：错误处理
  - log：日志记录
  - env_logger：日志后端

## 项目结构

```
.
├── Cargo.toml              # 项目配置和依赖
├── README.md               # 项目文档
├── hdc.md                  # 功能需求文档
├── AGENTS.md               # 开发规范文档
├── examples/               # 示例代码
│   └── hdc_cli.rs          # 命令行工具示例
└── src/
    ├── lib.rs              # 库核心实现
    └── resources/          # 平台资源目录
        └── linux/          # Linux 平台资源
            ├── hdc         # HDC 二进制文件
            └── libusb_shared.so  # USB 库依赖
```

## 快速开始

### 安装

在 `Cargo.toml` 中添加依赖：

```toml
[dependencies]
hdc_lib_rs = "0.1.0"
```

### 基本使用

```rust
use hdc_lib_rs::HdcClient;
use anyhow::Result;

fn main() -> Result<()> {
    // 使用默认服务器地址 (127.0.0.1:8710)
    let client = HdcClient::new()?;
    
    // 获取设备列表
    let targets = client.list_targets()?;
    println!("Connected devices: {:?}", targets);
    
    // 清理设备日志
    client.hilog_clean()?;
    
    Ok(())
}
```

### 自定义服务器地址

```rust
use hdc_lib_rs::HdcClient;
use anyhow::Result;

fn main() -> Result<()> {
    // 使用自定义服务器地址和端口
    let client = HdcClient::with_server("192.168.1.100", 8710)?;
    
    // 执行自定义命令
    let output = client.execute(["shell", "ls", "/tmp"])?;
    println!("{}", output);
    
    Ok(())
}
```

## API 文档

### HdcClient

#### 构造方法

- `new() -> Result<Self>`：创建客户端，使用默认服务器地址 `127.0.0.1:8710`
- `with_server(server_addr: &str, port: u16) -> Result<Self>`：创建客户端，指定服务器地址和端口
  - `server_addr`：必须是有效的 IPv4 或 IPv6 地址格式

#### 命令执行方法

- `execute<I, S>(&self, args: I) -> Result<String>`：执行 HDC 命令并返回输出
  - `args`：命令参数，接受任何实现了 `IntoIterator` 的类型
  
- `run_passthrough<I, S>(&self, args: I) -> Result<i32>`：透传执行 HDC 命令
  - 直接输出 stdout 和 stderr
  - 返回命令退出码

#### 特例接口

- `list_targets(&self) -> Result<Vec<String>>`：获取连接设备列表
  - 返回设备 SN 数组
  - 对应命令：`hdc -s {server_addr} list targets`

- `hilog_clean(&self) -> Result<()>`：清理设备日志
  - 对应命令：`hdc -s {server_addr} shell hilog -r`

## 示例使用

### 命令行工具示例

项目提供了命令行工具示例，可以透传所有 HDC 命令：

```bash
# 查看 HDC 帮助
cargo run --example hdc_cli -- --help

# 列出连接的设备
cargo run --example hdc_cli list targets

# 查看设备日志
cargo run --example hdc_cli shell hilog

# 清理设备日志
cargo run --example hdc_cli shell hilog -r

# 发送文件到设备
cargo run --example hdc_cli file send local_file.txt /data/local/

# 安装应用
cargo run --example hdc_cli install app.hap
```

### 使用日志

运行时启用日志输出：

```bash
# 显示调试日志
RUST_LOG=debug cargo run --example hdc_cli list targets

# 显示信息日志
RUST_LOG=info cargo run --example hdc_cli list targets
```

## 构建与测试

### 构建

```bash
# 开发模式构建
cargo build

# 发布模式构建
cargo build --release

# 构建示例
cargo build --examples
```

### 测试

```bash
# 运行所有测试
cargo test

# 运行单个测试
cargo test test_list_targets

# 运行测试并显示日志
RUST_LOG=debug cargo test -- --nocapture
```

### 代码检查

```bash
# 代码格式化
cargo fmt

# 代码检查
cargo check

# Clippy 静态分析
cargo clippy
```

## 开发指南

### 代码规范

- 使用 `rustfmt` 格式化代码
- 变量和函数使用 `snake_case` 命名
- 禁止使用 `unwrap`，使用显式异常处理
- 单个函数不超过 50 行
- 单行不超过 120 个字符
- 函数嵌套深度不超过 8 层
- 使用 `anyhow` 进行错误处理

### 添加新依赖

1. 编辑 `Cargo.toml` 的 `[dependencies]` 部分
2. 运行 `cargo build` 更新依赖

### 添加新功能接口

参考现有接口实现模式：

```rust
pub fn new_feature(&self) -> Result<OutputType> {
    let args = ["-s", &self.server_addr, "command", "args"];
    let output = self.execute(args)?;
    // 处理输出
    Ok(result)
}
```

## 注意事项

- 本项目目前仅支持 Linux 平台
- IPv6 地址格式需符合标准（如 `::1`、`2001:db8::1`）
- HDC 服务需在指定端口运行
- 建议在测试环境先验证功能

## 有用的资源

- [Rust 官方文档](https://doc.rust-lang.org)
- [OpenHarmony HDC 文档](https://gitee.com/openharmony/docs)
- [anyhow 错误处理库](https://docs.rs/anyhow)

## 许可证

本项目采用合适的开源许可证，具体请查看 LICENSE 文件。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进本项目。

## 更新日志

### v0.1.0

- 实现核心 HDC 调用功能
- 支持智能 HDC 检测和内置二进制提取
- 提供设备列表和日志清理接口
- 支持自定义服务器地址
- 添加命令行工具示例
- 完整的测试覆盖