跳转至

数据模型参考

最后更新：

本页逐项列出 evccapi-contract 1.3 的公开 Parcelable 字段。字段顺序也是当前手写 Parcel 编码顺序； 第三方不应自行复制另一套字段顺序，推荐直接依赖公开 Contract module。

记号与通用规则

  • “非空”指 Kotlin 类型不带 ?；String 可以是空字符串，List 默认是非空的空列表。
  • “必填”指构造函数没有默认值。AIDL 仍可能从异常或非官方实现收到无效数据，业务必须检查 status。
  • requestId 是调用方提供的关联标识。除 EvccShellRequest 外模型通常允许空字符串；需要跨日志定位的 请求仍建议使用不含控制字符的唯一 ID。Shell 的 ID 必须非空且在当前会话任务中唯一。
  • message、reason、displayValue 是面向展示或排障的文本，不应作为稳定分支条件；分支应使用状态、 类型、权限和能力 ID。
  • 状态全集和处理方式见状态与错误码，权限 ID 见权限与授权。

时间与代次

字段类别 当前 1.x 语义
createdAt、updatedAt Unix epoch 毫秒；0 表示未知或尚未设置
timeoutMs、durationMs 毫秒时长；使用单调时钟计算耗时时不应转换为日期
observedAt Long 来源观测时间；1.1 未承诺跨五源统一时基或单位，0 表示未知。Contract 的 EvccValue.of* 辅助函数默认填入 Unix epoch 毫秒，但车辆来源记录可能保留来源时间戳。不要跨来源排序，也不要未经判断直接格式化为日期
sourceGeneration 来源连接代次，不是时间戳；只在同一来源内比较相等/变化
grantRevision、capabilitiesRevision 不透明修订号，不是时间戳；用于判断是否发生变化，不推导时间或连续增量

如果未来需要统一 observedAt，应通过新字段或新主版本明确单位，不能在 1.x 中静默改变既有含义；参见 协议兼容与演进。

服务、会话与能力

EvccApiInfo

字段 Kotlin 类型 可空 默认值 含义
apiMajor Int 否 1 协议主版本；客户端必须相等
apiMinor Int 否 3 协议次版本
contractHash String 否 evccapi-1.3 契约基线标识，用于诊断，不代替能力发现
serviceVersionName String 否 "" EVCC 的展示版本名
serviceVersionCode Long 否 0 EVCC Android versionCode
capabilitiesRevision Long 否 0 能力目录修订号

EvccSessionInfo

字段 Kotlin 类型 可空 默认值 含义
sessionId String 否 "" 当前授权会话 ID；重连后可能变化
clientPackage String 否 "" 已通过 UID/包名/签名校验的客户端包名
grantedPermissions List<String> 否 emptyList() 本会话实际权限 ID；不要仅按预设推断
preset String 否 CUSTOM READ_ONLY、STANDARD、ADVANCED、ALL 或 CUSTOM；未知名称按实际 grantedPermissions 判断能力
grantRevision Long 否 0 本次授权记录修订号
createdAt Long 否 0 会话创建时间，Unix epoch 毫秒

EvccCapability

字段 Kotlin 类型 可空 默认值 含义
id String 否 "" 权限、来源或动作能力的稳定 ID
available Boolean 否 false 当前会话、来源和车型下是否可用
reason String 否 "" 展示说明，不作为机器判断条件
requiredPermission String 否 "" 所需权限 ID；空表示没有单一对应权限

能力查询同时反映当前授权和运行环境。应用应按 id 查找所需能力并检查 available，不要依赖列表顺序； 五源状态还可通过 querySourceStates() 获取。

EvccOperationResult

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 与请求关联的 ID
status String 否 OK 业务状态
message String 否 "" 展示或审计说明
acceptedCount Int 否 0 接受/成功处理的项目数
failedCount Int 否 0 失败项目数

isSuccess 是本地派生属性，不写入 Parcel；只有 OK 和 ACCEPTED 返回 true，PENDING 不属于该 快捷判断。异步 Shell 即使提交成功，仍必须等待最终回调。

属性选择与目录

EvccPropertySelector

字段 Kotlin 类型 可空 默认值 含义
id Long? 是 null 规范属性 ID
name String 否 "" 精确属性名
source String 否 AUTO AUTO 或一个明确来源
areaId Int? 是 null 明确区域；空时应用自动区域规则
resolutionMode String 否 AUTO_PRIORITY AUTO_PRIORITY、STRICT_UNIQUE 或 ALL_MATCHES

id 与 name 至少一个有效，本地构造空选择器会抛出 IllegalArgumentException；两者同时提供时作为 组合条件匹配。AUTO 顺序、区域歧义和五源差异见属性模型与读写。

EvccPropertyDescriptor

字段 Kotlin 类型 可空 默认值 含义
source String 否 "" 实际来源 ID；包括 VHAL、APVP、VEHICLE_AIDL、CAPI、ADAPT_API、SOA、ECARX_VHAL 与 Geely 来源
canonicalId Long 否 0 EVCC 规范 ID
nativeId String 否 "" 来源原生 ID 文本
aliases List<String> 否 emptyList() 来源或 EVCC 已知别名；双 ID 属性还会保留另一侧十六进制 ID
hexId String 否 "" 展示用十六进制 ID
name String 否 "" 属性名称
description String? 是 null 协议原生说明优先，否则使用 EVCC 按真实名称或“ID + 名称”精确匹配的说明；无可靠说明时为空
group String 否 "" 属性分组
areaType String 否 "" 区域类型
areaId Int 否 0 具体区域 ID
areaName String 否 "" 区域展示名称
dataType String 否 "" 来源归一后的数据类型文本
access String 否 "" 来源声明的读写能力文本
changeMode String 否 "" STATIC、ON_CHANGE、CONTINUOUS 等变化模式
enumOptions List<String> 否 emptyList() 来源动态枚举优先，否则使用 EVCC 精确匹配的 值=说明 选项
userNote String? 是 null 用户在 EVCC 属性诊断页保存的本地备注，不是协议权威元数据
sourceGeneration Long 否 0 生成此描述符时的来源代次

EvccPropertyRecord

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 请求关联 ID；监听事件通常可以为空
requestedSelector EvccPropertySelector? 是 null 原始选择器
resolvedSource String 否 "" 最终命中的实际来源
descriptor EvccPropertyDescriptor? 是 null 成功解析后的规范描述
value EvccValue? 是 null 读取或初始快照值；仅解析时可以为空
status String 否 PENDING 解析或读取状态
message String 否 "" 展示/排障说明
candidates List<EvccPropertyDescriptor> 否 emptyList() 来源或区域歧义候选项

不要以 value == null 或空字符串单独判断失败；先检查 status，再检查 value.initialized。解析、普通 读取、监听初始快照和来源切换都复用本模型。

EvccPageRequest

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 页面请求关联 ID
pageToken String 否 "" 下一页令牌；第一页为空
source String 否 AUTO 全部已启用来源或指定来源
query String 否 "" 目录搜索文本
limit Int 否 100 期望页大小；最大 500
includeValues Boolean 否 false 是否连同当前值返回；另需读取权限
mode String 否 DIRECTORY 普通目录或 LIVE_FULL_SCAN
snapshotToken String 否 "" 首页面返回的稳定快照令牌；续页必须回传

EvccPropertyPage

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 对应请求 ID
items List<EvccPropertyRecord> 否 emptyList() 当前页记录
nextPageToken String 否 "" 空表示分页结束
snapshotToken String 否 "" 本次不可变目录快照 ID
status String 否 OK 整页状态
message String 否 "" 展示/排障说明
sourceStates List<EvccSourceState> 否 emptyList() 与目录结果相关的来源状态

目录的稳定分页、缓存、限频和全量扫描风险见属性模型与读写与 实时全量扫描。

EvccSourceState

字段 Kotlin 类型 可空 默认值 含义
source String 否 "" 实际来源 ID
state String 否 UNAVAILABLE 当前来源状态
message String 否 "" 状态说明
sourceGeneration Long 否 0 当前来源连接代次
updatedAt Long 否 0 状态生成时间，Unix epoch 毫秒

类型化值

EvccValue

字段 Kotlin 类型 可空 默认值 含义
type String 否 NULL NULL、STRING、LONG、DOUBLE、BOOLEAN、JSON 或 BYTES_BASE64
stringValue String? 是 null STRING、JSON、BYTES_BASE64 的类型化载荷
longValue Long? 是 null LONG 载荷
doubleValue Double? 是 null DOUBLE 载荷
booleanValue Boolean? 是 null BOOLEAN 载荷
rawValue String? 是 null 来源原始或规范化文本，可能因大小限制省略
displayValue String 否 "" 面向用户的展示文本
initialized Boolean 否 false 是否已经获得真实初值
status String 否 PENDING 值本身的可用状态
observedAt Long 否 0 来源观测时间；1.1 不保证跨来源统一单位

同一 type 只读取对应的类型化字段；其他类型字段应视为空。rawValue 和 displayValue 不能替代类型 检查。Contract 提供 ofString、ofLong、ofDouble、ofBoolean 四个辅助构造函数，它们生成 initialized = true、status = AVAILABLE 的值。

写入、变量与动作

EvccWriteRequest

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 关联 ID
selector EvccPropertySelector 否 必填 写入目标
value EvccValue 否 必填 类型化写入值
validateOnly Boolean 否 false true 只预检查，不实际写入

AUTO 写入选中来源后不会向下一来源重放；批量写入不是事务。详见属性模型与读写。

EvccVariableRecord

字段 Kotlin 类型 可空 默认值 含义
name String 否 "" 变量名称
value EvccValue? 是 null 当前类型化值
status String 否 PENDING 读取或监听状态
message String 否 "" 展示/排障说明
updatedAt Long 否 0 最近更新时间，Unix epoch 毫秒
mutable Boolean 否 false 当前变量是否允许公开 API 写入/删除

EvccVariableWriteRequest

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 关联 ID
name String 否 必填 目标变量名
value EvccValue 否 必填 类型化变量值
validateOnly Boolean 否 false true 只校验权限、名称、类型和配额

变量命名、内置变量、可变性与配额见变量与动作。

EvccActionRequest

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 关联 ID
actionId String 否 必填 动作执行 ID，不是 action.* 能力 ID
argumentsJson String 否 "{}" JSON 对象参数
validateOnly Boolean 否 false true 只做能力、权限和参数预检查

动作 ID 和能力 ID 的区别见变量与动作。

Shell

EvccShellRequest

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 必填 非空且当前任务唯一的关联/取消 ID
command String 否 必填 待服务端策略检查的命令文本
timeoutMs Long 否 10000 请求超时毫秒；服务限制为 1～30 秒
includeRawOutput Boolean 否 false 为输出策略预留的请求标志；当前服务不按此字段切换返回结构，stdout/stderr 始终受授权和大小限制

EvccShellResult

字段 Kotlin 类型 可空 默认值 含义
requestId String 否 "" 对应 Shell 请求 ID
status String 否 PENDING 最终执行状态
exitCode Int 否 -1 进程退出码；未启动/无退出码时为 -1
stdout String 否 "" 标准输出，可能被清空或裁剪
stderr String 否 "" 标准错误，可能被清空或裁剪
truncated Boolean 否 false 输出是否因安全或 Binder 大小预算被裁剪
durationMs Long 否 0 从开始执行到结束的耗时毫秒

executeShell() 的同步返回值只表示提交/待确认状态；最终结果由 onShellCompleted() 返回。命令限制、 系统写入确认与取消语义见Shell 安全边界。

音乐模型（1.1）

音乐时钟使用 elapsedRealtime 毫秒；语义与示例见音乐专题。以下新类型具有独立固定 Parcel 布局。

EvccMusicState

字段 类型 默认值
status String EvccApiContract.Status.UNAVAILABLE
message String ""
trackId String ""
title String ""
artist String ""
album String ""
sourcePackage String ""
sourceAppName String ""
playbackState String "NONE"
positionMs Long -1L
positionAtElapsedMs Long 0L
durationMs Long -1L
playbackSpeed Float 0f
currentLyric String ""
lineStartMs Long -1L
lineEndMs Long -1L
lyricOffsetMs Long 0L
lyricsStatus String EvccApiContract.Status.NOT_FOUND
lyricsFormat String "none"
lyricsRevision Long 0L
artworkStatus String EvccApiContract.Status.NOT_FOUND
artworkRevision Long 0L
favoriteKnown Boolean false
favorite Boolean false
wholeBpm Float 0f
currentBpm Float 0f
bpmStatus String "unknown"
bpmSegmentStartMs Long -1L
bpmSegmentEndMs Long -1L
supportedCommands List<String> emptyList()
textTruncated Boolean false

EvccMusicCommand

字段 类型 默认值
requestId String ""
command String ""
positionMs Long 0L
favorite Boolean false
expectedTrackId String ""
validateOnly Boolean false

EvccMusicResource

字段 类型 默认值
status String EvccApiContract.Status.NOT_FOUND
message String ""
trackId String ""
revision Long 0L
mimeType String ""
sizeBytes Long 0L
descriptor ParcelFileDescriptor? null

API 1.2 音量组模型

以下各类型均为新增固定线格式，不改变已有 Parcelable；所有字段非空，顺序与表中一致。

类型 字段（类型与默认值，按编码顺序）
EvccVolumeGroupState status: String = UNAVAILABLE、message: String = ""、groupId: Int = -1、current: Int = -1、min: Int = -1、max: Int = -1
EvccVolumeGroupsResult status: String = UNAVAILABLE、message: String = ""、groups: List<EvccVolumeGroupState> = emptyList()
EvccVolumeSetRequest requestId: String = ""、groupId: Int = -1、value: Int = 0、validateOnly: Boolean = false
EvccVolumeAdjustRequest requestId: String = ""、groupId: Int = -1、delta: Int = 0、validateOnly: Boolean = false
EvccVolumeWriteResult requestId: String = ""、status: String = UNAVAILABLE、message: String = ""、groupId: Int = -1、target: Int = -1、min: Int = -1、max: Int = -1

只有成功状态下的数值有效，-1 表示尚未提供。target 是限幅后的下发/预检查目标；current 是系统读取值。两者不等价，详见音量组。