SANE 设备接口

SANE 设备接口用于在 Linux runtime 中发现 SANE 扫描仪、打开设备会话、读写设备参数、管理参数配置档，并提交异步扫描任务。sane.* 仅 Linux 可用；非 Linux 或 libsane 初始化失败时会返回 SANE 不可用状态。当前成者(CZUR)提供的 provider 为 private-sane-provider。

SANE 方法

方法	参数	响应 data	说明
`sane.status`	无	`available`，`platform`，`supported_platforms[]`，`sane_version`，`sane_major`，`sane_minor`，`reason`，`provider`	查询 SANE provider 可用性。
`sane.list`	`refresh?: boolean=true`，`include_detected?: boolean=false`	`devices[]`，`count`，`generation`，可选 `detected_devices[]`，`detected_count`，`provider`	列出可打开设备；可选返回已检测但不可通过 SANE backend 打开的设备。
`sane.watch_start`	无	`watching`，`generation`，`provider`	开始设备变化监听。会先推送 `sane.device_snapshot`，后续变化推送 `sane.device_changed`。
`sane.watch_stop`	无	`watching`，`generation`，`provider`	停止当前连接的设备变化监听。
`sane.open`	`device_id?: string`，`device_name?: string`	`opened`，`session_id`，`device`，`provider`	打开扫描仪会话。必须传 `device_id` 或 `device_name`。
`sane.close`	`session_id: string` 必填	`closed`，`was_opened`	关闭扫描仪会话；会话中有扫描任务运行时会返回设备忙。
`sane.get_options`	`session_id: string` 必填	`options[]`，`count`，`provider`	读取规范化后的 SANE options。
`sane.set_options`	`session_id: string` 必填，`options: object\|array` 必填	`applied`，`requires_reload`，`results[]`，`provider`	设置一个或多个 SANE options。
`sane.profile_list`	`session_id?: string`，`device_id?: string`，`device_name?: string`，`device_key?: string`	`profiles[]`，`count`，`provider`	列出已保存的 SANE 参数配置档。
`sane.profile_save`	`name: string` 必填，`profile_id?: string`，设备定位字段，`options?: object\|array`	`saved`，`profile`，`provider`	保存或覆盖一个参数配置档。
`sane.profile_apply`	`profile_id: string` 必填，`session_id?: string`	`applied`，`profile`，`provider`	应用配置档；传入 `session_id` 时会立即把配置档 options 写入当前设备会话。
`sane.profile_delete`	`profile_id: string` 必填	`deleted`，`profile`，`provider`	删除配置档。
`sane.scan`	`session_id: string` 必填，`options?: object\|array`，`output_type?: images\|pdf\|ofd\|tiff`，`output_format?: string`，`output_path?: string`，`output_dir?: string`，`export_type?: single-page\|multi-page`，`output?: object`，`pipeline?: ImageEnhancePipeline`	`accepted`，`task_id`，`task`，`provider`	提交异步扫描任务。同一会话同时只能运行一个扫描任务。
`sane.scan_get`	`task_id: string` 必填	`accepted`，`task_id`，`task`，`provider`	查询扫描任务快照。
`sane.scan_cancel`	`task_id: string` 必填	`accepted`，`task_id`，`task`，`provider`	请求取消扫描任务。

sane.open 当前不会应用 profile_id 或 options。需要设置参数时，先打开会话，再调用 sane.set_options 或带 session_id 的 sane.profile_apply。

设备与监听

sane.status 在 Linux 上返回当前 libsane 初始化状态；非 Linux 返回不可用。supported_platforms[] 当前为 ["linux"]。

devices[] 和 detected_devices[] 字段：

字段	类型	说明
`device_id`	string	SDK 内部设备 ID。
`device_name`	string	SANE backend 设备名，可用于 `sane.open`。
`vendor` / `model` / `type`	string	设备厂商、型号和类型。
`backend`	string	发现设备的 backend。
`status`	string	当前状态，通常为 `online`。
`discovery_source`	string	发现来源，例如 `sane_backend`。
`openable`	boolean	是否可通过 SANE backend 打开。

设备监听事件：

事件	触发时机	payload
`sane.device_snapshot`	`sane.watch_start` 成功后立即推送	`generation`，`devices[]`，`detected_devices[]`，`detected_count`，`added_devices[]`，`removed_devices[]`
`sane.device_changed`	监听期间设备集合变化	`generation`，`devices[]`，`detected_devices[]`，`detected_count`，`added_devices[]`，`removed_devices[]`

Options 与 Profiles

sane.get_options 返回的 options[] 是 SANE option 的规范化结构：

字段	类型	说明
`index`	number	SANE option 索引，可用于设置 option。
`name` / `title` / `description`	string	option 名称、标题和说明。
`group`	string	当前 option 所属分组。
`type`	string	`bool`、`int`、`fixed`、`string`、`button`、`group` 或 `unknown`。
`unit`	string	SANE 单位。
`value`	any	当前值，已按 JSON 类型解析。
`constraint`	object	约束信息。
`readonly` / `settable`	boolean	是否只读 / 是否可设置。
`automatic` / `inactive` / `advanced`	boolean	SANE capability 标记。
`requires_reload`	boolean	设置后是否需要重新读取 options。

constraint 字段：

字段	类型	说明
`type`	string	`none`、`range`、`list` 或 `string_list`。
`min` / `max` / `quant`	number	范围约束。
`values[]`	array	枚举值列表，元素已按 JSON 类型解析。

sane.set_options 的 options 支持两种写法：

json

{
  "resolution": 300,
  "mode": "Color"
}

json

[
  { "key": "resolution", "value": 300 },
  { "index": 3, "value": "Color" }
]

results[] 字段：

字段	类型	说明
`key`	string	设置时传入的 key。
`index`	number	实际匹配到的 option 索引。
`status`	string	`applied` 或 `rejected`。
`message`	string	应用结果说明。
`value`	any	本次设置的值。
`inexact`	boolean	是否被 SANE backend 调整为近似值。
`requires_reload`	boolean	是否需要重新读取 options。

profile 字段：

字段	类型	说明
`profile_id`	string	配置档 ID。未传时生成 `sane-profile-N`。
`device_key`	string	配置档关联的设备 key，来自 `device_key`、`device_id` 或 `device_name`。
`name`	string	配置档名称。
`options`	object	保存的 option 值，以 option key 或 index 为键。
`created_at` / `updated_at`	string	创建和更新时间。

扫描任务

sane.scan 会先把 SANE 扫描结果保存为页图片，再根据 output_type 处理最终输出：

输出目标	行为
`output_type=images`	直接返回扫描页图片；`output_format` 默认 `jpg`。
`output_type=pdf` / `ofd` / `tiff`	先扫描为页图片，扫描完成后调用文件转换生成目标文档。
`pipeline`	扫描页图片完成后先执行图像增强，再按目标输出。`pipeline` 结构见图像接口 / ImageEnhancePipeline。

output 对象可覆盖顶层输出参数：type、format、path、dir、export_type。如果 pipeline.target 指定了有效目标，也会覆盖扫描输出目标。

扫描页数由扫描仪 source 等 SANE option 决定：ADF 类 source 会连续扫描，非 ADF source 通常扫描单页。内部单次任务最多处理 1000 页。

task 字段：

字段	类型	说明
`task_id`	string	扫描任务 ID，例如 `sane-scan-1`。
`connection_id`	string	创建任务的 Command WS 连接 ID。
`session_id`	string	扫描设备会话 ID。
`status`	string	`queued`、`running`、`enhancing`、`converting`、`completed`、`failed`、`cancelled`。
`phase`	string	当前阶段，例如 `queued`、`applying-options`、`scanning`、`saving-page`、`enhancing`、`converting`、`completed`。
`progress`	number	进度，范围 `0..100`。
`page_count` / `current_page`	number	已输出页数和当前扫描页。
`output_type` / `output_format`	string	输出目标类型和格式。
`output_dir`	string	输出目录。
`export_type`	string	`single-page` 或 `multi-page`。
`output_path`	string	主输出路径。
`output_paths[]`	string[]	全部输出路径。
`last_page_path`	string	最近保存的扫描页路径。
`assets[]`	array	注册到本地资产服务的输出资产，含 `url`、`download_url`。
`message` / `error`	string	当前消息和失败原因。
`started_at` / `updated_at`	string	任务时间戳。
`cancel_requested`	boolean	是否已请求取消。

扫描任务事件为 sane.scan_changed，payload 包含 task_id、task 和 provider。

请求示例

查询状态和设备：

json

{ "request_id": "req-sane-status-001", "method": "sane.status", "params": {} }
{ "request_id": "req-sane-list-001", "method": "sane.list", "params": { "refresh": true, "include_detected": true } }

打开设备并设置参数：

json

{
  "request_id": "req-sane-open-001",
  "method": "sane.open",
  "params": {
    "device_id": "sane:scanner:001"
  }
}

json

{
  "request_id": "req-sane-set-001",
  "method": "sane.set_options",
  "params": {
    "session_id": "sane-session-1",
    "options": {
      "resolution": 300,
      "mode": "Color"
    }
  }
}

保存并应用配置档：

json

{
  "request_id": "req-sane-profile-save-001",
  "method": "sane.profile_save",
  "params": {
    "session_id": "sane-session-1",
    "device_id": "sane:scanner:001",
    "name": "Color 300dpi",
    "options": {
      "resolution": 300,
      "mode": "Color"
    }
  }
}

json

{
  "request_id": "req-sane-profile-apply-001",
  "method": "sane.profile_apply",
  "params": {
    "session_id": "sane-session-1",
    "profile_id": "sane-profile-1"
  }
}

提交图片扫描任务：

json

{
  "request_id": "req-sane-scan-001",
  "method": "sane.scan",
  "params": {
    "session_id": "sane-session-1",
    "output": {
      "type": "images",
      "format": "jpg",
      "dir": "/tmp/sdk-sane-pages",
      "export_type": "single-page"
    }
  }
}

提交带图像增强的 PDF 扫描任务：

json

{
  "request_id": "req-sane-scan-002",
  "method": "sane.scan",
  "params": {
    "session_id": "sane-session-1",
    "output": {
      "type": "pdf",
      "path": "/tmp/sdk-sane-output/scan.pdf",
      "export_type": "multi-page"
    },
    "pipeline": {
      "version": "image.enhance.pipeline.v1",
      "steps": [
        { "type": "blank_page_detect", "params": { "action": "drop" } }
      ],
      "target": {
        "type": "pdf",
        "path": "/tmp/sdk-sane-output/scan.pdf",
        "export_type": "multi-page"
      }
    }
  }
}

查询和取消扫描任务：

json

{ "request_id": "req-sane-get-001", "method": "sane.scan_get", "params": { "task_id": "sane-scan-1" } }
{ "request_id": "req-sane-cancel-001", "method": "sane.scan_cancel", "params": { "task_id": "sane-scan-1" } }

SANE 设备接口 ​

SANE 方法 ​

设备与监听 ​

Options 与 Profiles ​

扫描任务 ​

请求示例 ​

SANE 设备接口

SANE 方法

设备与监听

Options 与 Profiles

扫描任务

请求示例