3 EDSDK 对象（EDSDK Objects）

---

# 3 EDSDK 对象（EDSDK Objects）

EDSDK 采用分层对象模型来表示主机 PC 与相机之间的所有可控资源。
所有对象都通过 引用（Reference） 的形式进行访问与管理。

---

3.1 对象层级结构（Hierarchical Structure）

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

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

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

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

---

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

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

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

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

所有对象类型都继承自 EdsBaseRef

---

3.3 EdsCameraListRef（相机列表对象）

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

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

主要用途：

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

典型流程：

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

---

3.4 EdsCameraRef（相机对象）

## 3.4 EdsCameraRef（相机对象）

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

该对象用于：

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

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

---

3.5 EdsVolumeRef（存储卡对象）

## 3.5 EdsVolumeRef（存储卡对象）

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

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

可执行操作：

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

---

3.6 EdsDirectoryItemRef（目录项对象）

## 3.6 EdsDirectoryItemRef（目录项对象）

EdsDirectoryItemRef 表示：

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

该对象用于：

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

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

---

3.7 EdsStreamRef（流对象）

## 3.7 EdsStreamRef（流对象）

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

支持的流类型：

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

主要用途：

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

---

3.8 EdsImageRef（图像对象）

## 3.8 EdsImageRef（图像对象）

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

特点：

• 不能直接从相机端文件创建

• 必须先通过 EdsDownload 下载，再创建 EdsImageRef

• 可用于读取：

  • 图像属性
  • 缩略图
  • 图像参数（拍摄时的 Av / Tv / ISO 等）

---

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

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

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

包含内容：

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

使用前提：

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

---

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

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

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

规则：

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

⚠️ 开发注意事项：

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