3 EDSDK 对象（EDSDK Objects）

markdown 复制代码

# 3 EDSDK 对象（EDSDK Objects）

EDSDK 采用分层对象模型 来表示主机 PC 与相机之间的所有可控资源。

所有对象都通过 引用（Reference） 的形式进行访问与管理。

3.1 对象层级结构（Hierarchical Structure）

markdown 复制代码

## 3.1 对象层级结构（Hierarchical Structure）

EDSDK 使用一个以 相机列表（Camera List） 为根节点的层级结构来管理对象：

markdown 复制代码

CameraList
 ├─ Camera
 │   ├─ Volume（存储卡）
 │   │   ├─ Folder
 │   │   │   ├─ Image File
 │   │   │   └─ Audio File

所有连接到主机 PC 的相机都会包含在 EdsCameraListRef 中
每个相机、存储卡、文件夹、文件都被表示为一个对象
父对象可以通过 API 枚举其子对象

3.2 对象类型总览（Object Types Overview）

markdown 复制代码

## 3.2 对象类型总览（Object Types Overview）

EDSDK 中主要包含以下对象类型：

对象类型	说明
`EdsCameraListRef`	已连接相机的列表
`EdsCameraRef`	单个相机对象
`EdsVolumeRef`	相机中的存储介质（存储卡）
`EdsDirectoryItemRef`	文件夹或文件对象
`EdsImageRef`	已下载到主机的图像对象
`EdsStreamRef`	文件或内存流对象
`EdsEvfImageRef`	实时取景（Live View / EVF）图像对象

所有对象类型都继承自 EdsBaseRef

3.3 EdsCameraListRef（相机列表对象）

markdown 复制代码

## 3.3 EdsCameraListRef（相机列表对象）

EdsCameraListRef 表示当前通过 USB 或网络连接到主机 PC 的所有相机。

主要用途：

枚举已连接的相机数量
获取指定索引的相机对象（EdsCameraRef）

典型流程：

markdown 复制代码

1. 调用 `EdsGetCameraList`
2. 调用 `EdsGetChildCount` 获取相机数量
3. 调用 `EdsGetChildAtIndex` 获取具体相机对象

3.4 EdsCameraRef（相机对象）

markdown 复制代码

## 3.4 EdsCameraRef（相机对象）

EdsCameraRef 表示一台具体的 Canon 数码相机。

该对象用于：

打开 / 关闭会话（Session）
发送拍摄、对焦、变焦等命令
设置和获取相机属性
注册事件回调
获取存储卡对象（EdsVolumeRef）

所有对相机的控制操作，都必须在 已打开 Session 的情况下 进行。

3.5 EdsVolumeRef（存储卡对象）

markdown 复制代码

## 3.5 EdsVolumeRef（存储卡对象）

EdsVolumeRef 表示相机中的一张存储卡。

如果相机支持双卡，则每张卡对应一个 EdsVolumeRef
该对象用于访问存储卡上的文件和文件夹

可执行操作：

获取存储卡容量信息
枚举文件夹和文件
格式化存储卡（⚠️高风险操作）

3.6 EdsDirectoryItemRef（目录项对象）

markdown 复制代码

## 3.6 EdsDirectoryItemRef（目录项对象）

EdsDirectoryItemRef 表示：

文件夹（Folder）
文件（Image / Movie / Audio）

该对象用于：

获取文件或文件夹信息
下载文件
删除文件
设置文件属性（只读、隐藏等）

文件在 相机端 与 主机端 使用的是不同的对象模型

3.7 EdsStreamRef（流对象）

markdown 复制代码

## 3.7 EdsStreamRef（流对象）

EdsStreamRef 表示一个 I/O 数据流，用于文件传输。

支持的流类型：

文件流（磁盘文件）
内存流（内存缓冲区）

主要用途：

将相机中的文件下载到主机
将主机文件加载为图像对象
存储实时取景数据

3.8 EdsImageRef（图像对象）

markdown 复制代码

## 3.8 EdsImageRef（图像对象）

EdsImageRef 表示 已下载到主机 PC 的图像数据。

特点：

不能直接从相机端文件创建
必须先通过 EdsDownload 下载，再创建 EdsImageRef
可用于读取：
- 图像属性
- 缩略图
- 图像参数（拍摄时的 Av / Tv / ISO 等）

3.9 EdsEvfImageRef（实时取景图像对象）

markdown 复制代码

## 3.9 EdsEvfImageRef（实时取景图像对象）

EdsEvfImageRef 表示实时取景（Live View / EVF）图像数据。

包含内容：

实时画面
变焦信息
对焦点信息
直方图数据

使用前提：

相机必须支持 Live View
必须先启用 EVF 输出到 PC

3.10 对象生命周期与引用计数（Reference Counting）

markdown 复制代码

## 3.10 对象生命周期与引用计数（Reference Counting）

EDSDK 使用 引用计数（Reference Count） 来管理对象生命周期。

规则：

对象创建时，引用计数 = 1
每次 EdsRetain → 引用计数 +1
每次 EdsRelease → 引用计数 −1
引用计数为 0 时，对象会被自动释放

⚠️ 开发注意事项：

markdown 复制代码

- 通过 API 获取的对象通常已经隐式增加了引用计数
- 每一个获取的对象，最终都必须对应一次 `EdsRelease`
- 否则会导致内存泄漏或 SDK 状态异常