# wmpf-cli 使用必读

## 1. 关于不同版本的接口

WMPF 目前提供两套形式的接口

- v2 版接口（推荐）：WMPF 2.1.0 版本开始，我们提供了封装更为完整的 WMPFxxxApi 系列接口，接口能力也更为完善，建议使用新版本 WMPF 的开发者优先使用这种调用方式。
- v1 版接口：WMPF 发布开始提供了基于 `WMPFIPCInvoker` 的一系列 IPC 接口，来承载 WMPF 的基础能力和扩展能力。但是这套接口封装比较简单，开发者调用比较繁琐，而且容易出错。v1 版接口在最新的 WMPF 上仍可以正常使用，但已停止维护，不再迭代新功能。

## 2. v2 版接口使用指南

### 2.1 注意事项

- 需配合 **WMPF >= 2.1.0 (WMPF-cli >= 2.1.0)** 正式版本使用。部分低版本的 wmpf-cli 虽也会支持部分能力，但可能与文档描述有出入，不保证可用性。
- 除了 `WMPFBooit.init` 外，其他接口均需要在 worker thread 中调用。**请勿在主线程调用**。
- 调用错误会通过异常形式抛出，请开发者注意**捕获和处理异常**。

### 2.2 异常处理

v2 版接口接口调用失败时，会抛出 `WMPFApiException` 异常，请开发者注意处理。

捕获 `WMPFApiException` 后，可以根据 `errType`，`errCode`，`errMsg` 来分析和处理错误。`errType`，`errCode` 的取值请参考 [TaskError 文档](client/TaskError)。

### 2.3 从 `WMPFIPCInvoker` 接口迁移

**(1) 初始化和激活流程**

- v1 版接口：使用 [`ActivateDevice`](client/ActivateDevice)；
- v2 版接口：先使用 [WMPFBoot.init](cli/boot/init) 初始化，再调用 [WMPFDeviceApi.activateDevice](cli/device/activateDevice) 激活设备。

**(2) 切换接口**

v1 版接口文档中会指出建议替换的新接口，可以参考具体接口的文档。

### 2.4 自动激活

WMPF-cli 2.2 开始，在使用 v2 版接口时支持自动激活设备并维护状态。在 [WMPFBoot.init](cli/boot/init) 初始化后即可调用 WMPF 接口，通常情况下开发者不需要再显式调用 [WMPFDeviceApi.activateDevice](cli/device/activateDevice) 接口进行设备激活。

某些情况下，开发者可能也需要进行手动激活：
- 如果希望提前校验设备激活状态，仍然可以直接调用[WMPFDeviceApi.activateDevice](cli/device/activateDevice) 接口。
- 在 [registerDeviceActivationOutdatedEventListener](cli/device/registerDeviceActivationOutdatedEventListener) 监听到设备激活状态失效时，可以在必要时（例如网络切换时）重试激活。

## 3. 新旧接口实现混用

对于无法全部迁移，或者部分功能新接口未支持的情况，支持新旧接口混用。

- 若使用 v2 版接口激活，激活成功后，可以使用 `WMPFDeviceApi.getInvokeToken()` 方法获取 `invokeToken`，然后按照之前的方式调用 v1 版接口即可。
- 若使用 v1 版接口激活，激活成功后，可以使用 `WMPFDeviceApi.setInvokeToken()` 方法设置 `invokeToken`，然后调用 v2 版接口即可。

## 4. WMPF cli 和 WMPF Service APK 的版本对应关系

通常情况下，建议 WMPF cli 和 WMPF Service APK 使用相同版本。但使用不匹配的版本可能因为数据序列化方式的变化而导致接口调用失败。

如果因为兼容等原因不得不使用不匹配的版本，建议提前测试各项功能正常。

## 5. 多进程应用接入 wmpf-cli

wmpf-cli 建议固定应用内指定进程（如主进程）接入，不建议应用内多个进程同时使用 wmpf-cli。如果你遇到 `wait wakeup activity result timeout` 错误，则说明你应用内不同进程调用了 wmpf-cli 接口.

## 6. WMPF 系统权限

自 Android 10 起，[Android 系统开始限制后台应用启动 Activity](https://developer.android.com/guide/components/activities/background-starts?hl=zh-cn)，因此 WMPF 默认无法通过接口拉起小程序 Activity。
需要给 WMPF 提供以下权限才能正常使用 wmpf-cli 启动小程序：
1. 自启动权限：使得接入了 wmpf-cli 的应用可以在 WMPF 进程未启动的情况下通过 wmpf-cli 接口启动 WMPF 后台进程。
2. 后台弹出页面权限：使得 WMPF 可以在后台启动小程序 Activity。

## 7. ContentProvider 相关

推荐系统内只有一个应用接入 wmpf-cli, 因为 WMPF ContentProvider 系列接口使用了 authority `com.tencent.wmpf.cli.provider`, 只能有一个应用监听到基于 ContentProvider 提供的相关接口和事件。