# devGrpcClient - gRPC设备客户端库

## 简介

devGrpcClient 是一个基于 gRPC 的跨平台设备通信客户端库，提供同步和异步RPC调用接口。该库封装了设备操作的完整功能，支持SSL/TLS安全连接。

## 主要特性

- **完整的设备操作接口**：支持 Get/Set/Update/Add/Del/Action/Message 操作
- **同步与异步调用**：既支持阻塞式同步调用，也支持高性能异步批量调用
- **SSL/TLS加密**：所有通信均通过SSL/TLS加密，保证数据安全
- **跨平台支持**：支持 Linux 和 Windows 平台
- **C++ 接口**：提供简洁的C++接口，易于集成

## 快速开始

### 环境准备

详细的环境配置步骤请参考：**[环境配置说明.md](./环境配置说明.md)**

**必需依赖：**
- gRPC 1.30.2（安装在 `/usr/local/grpc-1.30.2`）
- Abseil C++ 20210324.2（安装在 `/usr/local/abseil-20210324.2`）
- Protobuf（系统包管理器安装）
- CMake 3.10+
- C++17 编译器

### 编译项目

```bash
# 在项目根目录下
cd /path/to/DriverPlatform-V3.1
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make devGrpcClient -j$(nproc)
```

编译完成后，库文件和头文件会自动复制到 `Deliver/` 目录：
- 库文件：`Deliver/lib/libdevGrpcClient.so*`
- 头文件：`Deliver/include/devGrpcClient.h`

### 使用示例

#### 1. 包含头文件

```cpp
#include "devGrpcClient.h"
```

#### 2. 创建客户端连接

```cpp
// 连接到服务器（需要提供 root.crt 证书文件）
GrpcDeviceClient* client = CreateClient("192.168.1.100:9010");
```

#### 3. 打开设备

```cpp
int result = client->OpenDevice("DIOS/DEVICE/Detector", "");
if (result != 2) {
    std::cerr << "设备打开失败" << std::endl;
}
```

#### 4. 同步调用

```cpp
std::string devRes, msg;
int ret = client->Get("AcqMode", devRes, msg);
std::cout << "返回码: " << ret << ", 数据: " << devRes << std::endl;

// 设置参数
ret = client->Set("Brightness", "{\"value\":80}", devRes, msg);

// 执行动作
ret = client->Action("StartAcquisition", "", devRes, msg);
```

#### 5. 异步批量调用

```cpp
// 开始异步调用模式
client->BeginAyncWait();

// 批量发起异步请求
int count = 0;
count = client->AsyncAction("EnterExam", "");
count = client->AsyncAction("RESET", "");
count = client->AsyncAction("PrepareAcquisition", "");

// 等待所有请求完成
client->WaitAllComplete();

// 获取结果
for (int i = 0; i < count; i++) {
    std::string action, result, resultMsg;
    int code = client->GetAsyncResult(i, action, result, resultMsg);
    std::cout << "异步调用[" << i << "] " << action
              << " 返回码=" << code << std::endl;
}

// 结束异步模式
client->EndAync();
```

#### 6. 释放客户端

```cpp
FreeClient(client);
```

### 完整示例程序

```cpp
#include "devGrpcClient.h"
#include <iostream>

int main() {
    // 创建客户端
    GrpcDeviceClient* client = CreateClient("localhost:9010");

    // 打开设备
    if (client->OpenDevice("DIOS/DEVICE/Detector", "") != 2) {
        std::cerr << "设备打开失败" << std::endl;
        FreeClient(client);
        return -1;
    }

    // 同步获取数据
    std::string data, msg;
    client->Get("DeviceInfo", data, msg);
    std::cout << "设备信息: " << data << std::endl;

    // 释放客户端
    FreeClient(client);
    return 0;
}
```

编译示例程序：

```bash
g++ -o example example.cpp \
  -I/path/to/Deliver/include \
  -L/path/to/Deliver/lib \
  -ldevGrpcClient \
  -Wl,-rpath,/path/to/Deliver/lib
```

## API 接口说明

### 设备管理接口

- `int OpenDevice(string devUri, string group)` - 打开设备
- `int CloseDevice()` - 关闭设备
- `string GetDeviceTarget()` - 获取设备目标地址
- `int GetClientStatus()` - 获取客户端连接状态
- `string GetOpendDeviceResource()` - 获取已打开的设备资源

### 同步操作接口

所有同步接口返回操作结果码（2表示成功），并通过参数返回结果数据：

- `int Get(string devResource, string& devRes, string& calResMsg, ...)` - 获取数据
- `int Set(string devResource, string reqParams, string& devRes, string& calResMsg, ...)` - 设置数据
- `int Update(string devResource, string reqParams, string& devRes, string& calResMsg, ...)` - 更新数据
- `int Add(string devResource, string reqParams, string& devRes, string& calResMsg, ...)` - 添加数据
- `int Del(string devResource, string reqParams, string& devRes, string& calResMsg, ...)` - 删除数据
- `int Action(string devResource, string reqParams, string& devRes, string& calResMsg, ...)` - 执行动作
- `int Message(string devResource, string reqParams, string& devRes, string& calResMsg, ...)` - 发送消息

### 异步操作接口

异步接口用于批量并发执行操作，提高性能：

- `int BeginAyncWait()` - 开始异步调用模式
- `int AsyncAction(string devResource, string reqParams, ...)` - 异步执行动作
- `int AsyncMessage(string devResource, string reqParams, ...)` - 异步发送消息
- `void WaitAllComplete()` - 等待所有异步调用完成
- `int GetAsyncResult(int idx, string& devResource, string& devRes, string& calResMsg)` - 获取异步结果
- `void EndAync()` - 结束异步模式，清理资源

### 工厂函数

- `GrpcDeviceClient* CreateClient(const char* serverAddress)` - 创建客户端实例
- `void FreeClient(GrpcDeviceClient* client)` - 释放客户端实例

## 返回码说明

| 返回码 | 含义 |
|--------|------|
| 2 | 成功 |
| 0 | 失败（通用） |
| < 0 | 网络错误（负数为gRPC错误码） |

## 证书配置

客户端使用SSL/TLS加密连接，需要提供服务器的根证书文件 `root.crt`。

**证书文件位置：** 默认从当前工作目录加载 `root.crt`

如需使用其他路径，可修改 `devGrpcClient.cpp` 中的证书加载代码：

```cpp
ssl_options.pem_root_certs = LoadStringFromFile("/path/to/root.crt");
```

## 项目结构

```
devGrpcClient/
├── CMakeLists.txt              # CMake构建配置
├── README.md                   # 本文件
├── 环境配置说明.md             # 详细的环境配置文档
├── protos/
│   └── device-sm.proto         # gRPC服务定义文件
└── src/
    ├── devGrpcClient.h         # 客户端头文件
    └── devGrpcClient.cpp       # 客户端实现
```

## 技术栈

- **通信协议：** gRPC 1.30.2
- **序列化：** Protocol Buffers 3
- **C++标准：** C++17
- **加密：** SSL/TLS（基于OpenSSL）
- **线程库：** std::thread（C++11）
- **依赖库：** Abseil C++ 20210324.2

## 常见问题

### 1. 编译时找不到gRPC库

请确保gRPC已正确安装在 `/usr/local/grpc-1.30.2`，详见[环境配置说明.md](./环境配置说明.md)。

### 2. 运行时找不到动态库

```bash
export LD_LIBRARY_PATH=/path/to/Deliver/lib:$LD_LIBRARY_PATH
```

### 3. 证书加载失败

确保 `root.crt` 文件与可执行文件在同一目录，或使用绝对路径。

### 4. 连接超时

检查服务器地址和端口是否正确，防火墙是否允许连接。

更多问题请参考 **[环境配置说明.md](./环境配置说明.md)** 的"常见问题"章节。

## 性能优化建议

1. **使用异步接口进行批量操作**：可显著提高并发性能
2. **复用客户端连接**：避免频繁创建和销毁客户端
3. **合理设置超时时间**：根据网络环境调整RPC超时时间
4. **使用连接池**：在多线程环境中使用连接池管理客户端实例

## 版本历史

### v1.0.0 (2025-10-22)
- 初始版本发布
- 支持完整的设备操作接口
- 实现同步和异步RPC调用
- 支持SSL/TLS加密连接

## 许可证

本项目为内部使用项目，版权归公司所有。

## 联系方式

如有问题或建议，请联系项目维护者。

---

**注意：** 在生产环境部署前，请务必阅读 **[环境配置说明.md](./环境配置说明.md)** 完成所有环境配置。