# FreeRDP 3 客户端 API 参考（Ubuntu 24.04 / freerdp3-dev）

> 用途：kiosk-shell 内嵌 FreeRDP 客户端时使用，避免拉起外部进程（开发方案 3.2 节）。
> 记录时间：2026-10-23

## 包名
- 运行时：`libfreerdp-client3-3`、`libfreerdp3-3`
- 开发：`freerdp3-dev`（Ubuntu 24.04 提供 `freerdp3-dev` 与 `libfreerdp-client3-3-dev`）
- pkg-config 名称：`freerdp3`、`freerdp3-client`（安装后以 `pkg-config --list-all | grep freerdp` 实测为准）

## 关键头文件
| 头文件 | 用途 |
|---|---|
| `freerdp/client.h` | 客户端主入口、freerdp_client_context_new / freerdp_client_context_free |
| `freerdp/freerdp.h` | 核心上下文 |
| `freerdp/settings.h` | 连接参数设置（freerdp_settings_new / set) |
| `freerdp/channels/cliprdr.h` | 剪贴板通道 |
| `freerdp/gdi/gfx.h` | GFX 图形管线（AVC420/AVC444/RFX 能力） |
| `freerdp/crypto/tls.h` | TLS |

## 最小连接流程（伪代码）
```c
freerdp_client_context* ctx = freerdp_client_context_new();
RdpClientContext* cctx = ...;
freerdp_settings_new(0);          // 释放: freerdp_settings_free
freerdp_set_pointer / freerdp_set_keyboard ...  // 输入回调
ctx->Connect = ...;               // 事件表
freerdp_client_context_new / connect
```

## 注意事项
- `/gfx` 命令行语法在 3.32.1 上必须用 `|` 分隔的能力组合（如 `progressive|RFX|AVC420|AVC444`），
  单独 `AVC420` 会解析失败。API 侧对应 `gfx` 能力位设置。