AIDL API Reference¶

最后更新：2026-10-13

适用协议：EVCC 开放 API 1.4

本节按 AIDL 接口和方法组织，回答四个问题：调用什么方法、传入什么、同步返回什么、是否还有异步回调。如果你第一次接触 EVCC，先记住：EVCC 是服务端，你的 Android 应用是 Binder 客户端；属性是车辆或系统数据，变量是 EVCC 自动化与 Lua 共用的进程级数据，动作是 EVCC 明确开放的操作。

公开 evccapi-contract module 中的 AIDL 与 Parcelable 是二进制契约的唯一权威来源。本文不把 AIDL 伪装成 HTTP 接口，也不会为 Parcelable 虚构 JSON 请求格式；只有 EvccActionRequest.argumentsJson 本身是 JSON 字符串。

契约标识¶

API              1.3
contractHash     evccapi-1.3
EVCC package     com.kooo.evcc
bind action      com.kooo.evcc.evccapi.BIND
settings action  com.kooo.evcc.evccapi.OPEN_SETTINGS
manifest 权限    com.kooo.evcc.permission.ACCESS_EVCC_API

Manifest 普通权限只是绑定服务的前置条件。EVCC 还会校验调用 UID、唯一包名、APK 证书摘要、用户授权及授权修订号；应用必须由用户在 EVCC 中授权后才能建立会话。

接口索引¶

接口	职责	文档
`IEvccApi`	查询协议版本并建立授权会话	根接口
`IEvccApiSession`	属性、变量、动作、Shell 和会话操作	会话接口
`IEvccApiCallback`	接收监听事件、Shell 最终结果、撤权和重同步通知	回调接口

方法总览¶

`IEvccApi`¶

方法	同步返回	用途
`getApiInfo()`	`EvccApiInfo`	在建会话前读取协议与 EVCC 版本
`openSession(packageName, callback)`	`IEvccApiSession`	校验调用身份和用户授权并建立会话

`IEvccApiSession`¶

方法	所需分类权限	同步返回	额外回调
`getSessionInfo()`	有效会话	`EvccSessionInfo`	无
`queryCapabilities()`	有效会话	`List<EvccCapability>`	无
`resolveProperty()`	`property.directory`	`EvccPropertyRecord`	无
`readProperty()`	`property.read`	`EvccPropertyRecord`	无
`readProperties()`	`property.read`	`List<EvccPropertyRecord>`	无
`replaceSubscriptions()`	`property.listen` + `property.read`	`EvccOperationResult`	`onPropertyEvent()`、`onSourceStateChanged()`
`queryPropertyDirectory()`	`property.directory`，按参数可能增加权限	`EvccPropertyPage`	无
`querySourceStates()`	`property.directory`	`List<EvccSourceState>`	无
`writeProperty()`	`property.write`	`EvccOperationResult`	无
`writeProperties()`	`property.write`	`List<EvccOperationResult>`	无
`queryVariables()`	`variable.read`	`List<EvccVariableRecord>`	无
`readVariable()`	`variable.read`	`EvccVariableRecord`	无
`replaceVariableSubscriptions()`	`variable.listen` + `variable.read`	`EvccOperationResult`	`onVariableEvent()`
`writeVariable()`	`variable.write`	`EvccOperationResult`	无
`deleteVariable()`	`variable.delete`	`EvccOperationResult`	无
`executeAction()`	由 `actionId` 决定	`EvccOperationResult`	无
`executeShell()`	`shell.exec`，系统写入另需 `shell.system_write`	`EvccOperationResult`	`onShellCompleted()`
`cancel()`	有效会话	`EvccOperationResult`	运行中的 Shell 通常仍产生最终回调
`close()`	有效会话	`void`	主动关闭不回调自身
`readMusicState()`	`music.read`	`EvccMusicState`	无
`setMusicSubscription()`	`music.listen` + `music.read`	`EvccOperationResult`	`onMusicStateChanged()`
`openMusicLyrics()`	`music.read`	`EvccMusicResource`	无
`openMusicArtwork()`	`music.read`	`EvccMusicResource`	无
`sendMusicCommand()`	`music.control`	`EvccOperationResult`	无
`queryVolumeGroups()`	`volume.read`	`EvccVolumeGroupsResult`	无
`readVolumeGroup()`	`volume.read`	`EvccVolumeGroupState`	无
`setVolumeGroup()`	`volume.control`	`EvccVolumeWriteResult`	无
`adjustVolumeGroup()`	`volume.control`	`EvccVolumeWriteResult`	无

`IEvccApiCallback`¶

回调	触发条件	是否带事件序号
`onSessionClosed()`	撤权、服务关闭或会话失效	否
`onPropertyEvent()`	属性初值、变化或 AUTO 来源切换	是
`onVariableEvent()`	变量初值、变化或删除	是
`onSourceStateChanged()`	已订阅属性的来源状态变化	是
`onShellCompleted()`	Shell 获得最终结果	否，以 `requestId` 关联
`onResyncRequired()`	普通事件队列出现缺口	回调参数描述缺口

所有方法共有的调用规则¶

IEvccApiSession 方法是同步 Binder 调用。属性解析/读取/写入、目录、批量调用、动作和 Shell 提交不应在 Android 主线程执行。
IEvccApiCallback 是 oneway。回调可能与发起调用的线程并发执行，客户端必须快速入队，不能在 Binder 回调线程执行数据库、文件或网络 I/O。
业务失败通常写入返回模型的 status，Binder 断连或 Parcel 不兼容则表现为 RemoteException 等 Android IPC 异常。两者要分开处理。
message、reason 是给人看的诊断文本，不是稳定枚举。程序分支必须使用 status、能力 ID、权限 ID 和事件类型。
单次 Binder 数据预算为 512 KiB。服务会在约 480 KiB 的有效预算内裁剪或返回 PAYLOAD_TOO_LARGE；不要依赖 Binder 理论上限。
当前 Parcelable 使用固定字段顺序的手写 Parcel 编码。客户端应依赖公开 Contract，不要复制一套自定义模型或自行调整字段顺序。

字段定义见数据模型参考，状态处理见状态与错误码，授权流程见权限与授权。

API 1.1 音乐方法¶

方法	返回	权限
`readMusicState()`	`EvccMusicState`	music.read
`setMusicSubscription(boolean enabled)`	`EvccOperationResult`	开启需要 music.listen + music.read；关闭仅需有效会话
`openMusicLyrics(String trackId, long revision)`	`EvccMusicResource`	music.read
`openMusicArtwork(String trackId, long revision)`	`EvccMusicResource`	music.read
`sendMusicCommand(in EvccMusicCommand request)`	`EvccOperationResult`	music.control

均为同步 Binder 调用，应在工作线程执行。完整资源、控制、订阅与错误语义见音乐专题。

Geely 属性来源¶

新增 GEELY_AIDL、GEELY_CAPI。selector 的 name 使用目录中的通道限定名称，例如 signal:0x4061，另传 areaId。目录 name 显示 SDK 英文属性名，aliases 保留通道限定名称及完整引用，nativeId 保留原始数字 ID；未提供区域时也必须唯一；只传数字 ID 必须唯一，否则返回歧义及候选。既有 Parcelable 字段布局保持不变。

AUTO 在原有来源之后依次追加 Geely CAPI、Geely AIDL；显式选源不跨源回退。Sensor 只读。字节值读写均使用 base64: 字符串，保留原始字节。连接开关或云端可见性关闭时不可访问。

ECARX 原生 VHAL 属性来源（API 1.4）¶

新增 ECARX_VHAL，仅在精确适配的领克 900（L946）可用。它对 API 始终表现为一个来源，目录、读取、监听和写入全部来自同一个 HIDL VHAL 会话。AUTO 在该车型上优先解析 ECARX_VHAL；显式选源仍不跨源回退。目录 access 取自原生配置，并在执行前再次校验区域、类型和读写权限。

API 1.2 音量组¶

音量组接口与调用规则包含四个追加方法、目标值语义、权限、配额及失败处理。