SANE Device API

The SANE device API discovers SANE scanners in a Linux runtime, opens scanner sessions, reads and writes device options, manages option profiles, and submits asynchronous scan tasks. sane.* is Linux-only; non-Linux runtimes or libsane initialization failures return a SANE unavailable status. The current CZUR provider is private-sane-provider.

SANE Methods

Method	Parameters	Response data	Notes
sane.status	none	available, platform, supported_platforms[], sane_version, sane_major, sane_minor, reason, provider	Gets SANE provider availability.
sane.list	refresh?: boolean=true, include_detected?: boolean=false	devices[], count, generation, optional detected_devices[], detected_count, provider	Lists openable devices; optionally returns devices detected but not openable through a SANE backend.
sane.watch_start	none	watching, generation, provider	Starts device watching. It first pushes sane.device_snapshot; later changes push sane.device_changed.
sane.watch_stop	none	watching, generation, provider	Stops device watching for the current connection.
sane.open	device_id?: string, device_name?: string	opened, session_id, device, provider	Opens a scanner session. One of device_id or device_name is required.
sane.close	session_id: string required	closed, was_opened	Closes a scanner session; returns device-busy while a scan task is running.
sane.get_options	session_id: string required	options[], count, provider	Gets normalized SANE options.
sane.set_options	session_id: string required, options: object|array required	applied, requires_reload, results[], provider	Sets one or more SANE options.
sane.profile_list	session_id?: string, device_id?: string, device_name?: string, device_key?: string	profiles[], count, provider	Lists saved SANE option profiles.
sane.profile_save	name: string required, profile_id?: string, device location fields, options?: object|array	saved, profile, provider	Saves or overwrites an option profile.
sane.profile_apply	profile_id: string required, session_id?: string	applied, profile, provider	Applies a profile; when session_id is provided, profile options are written to the current device session.
sane.profile_delete	profile_id: string required	deleted, profile, provider	Deletes a profile.
sane.scan	session_id: string required, 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	Submits an asynchronous scan task. One session can run only one scan task at a time.
sane.scan_get	task_id: string required	accepted, task_id, task, provider	Gets a scan task snapshot.
sane.scan_cancel	task_id: string required	accepted, task_id, task, provider	Requests cancellation for a scan task.

sane.open currently does not apply profile_id or options. To set parameters, open the session first, then call sane.set_options or sane.profile_apply with session_id.

Devices and Watching

sane.status returns current libsane initialization state on Linux; non-Linux runtimes return unavailable. supported_platforms[] is currently ["linux"].

devices[] and detected_devices[] fields:

Field	Type	Notes
device_id	string	SDK internal device ID.
device_name	string	SANE backend device name, usable with sane.open.
vendor / model / type	string	Device vendor, model, and type.
backend	string	Backend that discovered the device.
status	string	Current status, usually online.
discovery_source	string	Discovery source, such as sane_backend.
openable	boolean	Whether the device can be opened through a SANE backend.

Device watch events:

Event	Trigger	Payload
sane.device_snapshot	Pushed immediately after successful sane.watch_start	generation, devices[], detected_devices[], detected_count, added_devices[], removed_devices[]
sane.device_changed	Device set changes while watching	generation, devices[], detected_devices[], detected_count, added_devices[], removed_devices[]

Options and Profiles

sane.get_options returns normalized SANE options:

Field	Type	Notes
index	number	SANE option index, usable when setting an option.
name / title / description	string	Option name, title, and description.
group	string	Current option group.
type	string	bool, int, fixed, string, button, group, or unknown.
unit	string	SANE unit.
value	any	Current value parsed as JSON.
constraint	object	Constraint information.
readonly / settable	boolean	Whether the option is read-only / settable.
automatic / inactive / advanced	boolean	SANE capability flags.
requires_reload	boolean	Whether options should be reloaded after setting.

constraint fields:

Field	Type	Notes
type	string	none, range, list, or string_list.
min / max / quant	number	Range constraint.
values[]	array	Enumerated values parsed as JSON.

sane.set_options accepts two option shapes:

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

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

results[] fields:

Field	Type	Notes
key	string	Key provided in the set request.
index	number	Matched option index.
status	string	applied or rejected.
message	string	Result message.
value	any	Value used for this set attempt.
inexact	boolean	Whether the SANE backend adjusted the value approximately.
requires_reload	boolean	Whether options should be reloaded.

profile fields:

Field	Type	Notes
profile_id	string	Profile ID. Generated as sane-profile-N when omitted.
device_key	string	Device key from device_key, device_id, or device_name.
name	string	Profile name.
options	object	Saved option values keyed by option key or index.
created_at / updated_at	string	Created and updated timestamps.

Scan Tasks

sane.scan first saves SANE scan output as page images, then processes final output according to output_type:

Output target	Behavior
output_type=images	Returns scanned page images directly; output_format defaults to jpg.
output_type=pdf / ofd / tiff	Scans page images first, then calls file conversion after scan completion to generate the target document.
pipeline	Runs image enhancement after scanned page images are available, then writes the target output. See Image API / ImageEnhancePipeline.

The output object can override top-level output parameters: type, format, path, dir, and export_type. If pipeline.target specifies a valid target, it can also override the scan output target.

The number of scanned pages is controlled by scanner options such as source: ADF-like sources scan continuously, while non-ADF sources usually scan one page. One task has an internal limit of 1000 pages.

task fields:

Field	Type	Notes
task_id	string	Scan task ID, such as sane-scan-1.
connection_id	string	Command WS connection ID that created the task.
session_id	string	Scanner session ID.
status	string	queued, running, enhancing, converting, completed, failed, or cancelled.
phase	string	Current phase, such as queued, applying-options, scanning, saving-page, enhancing, converting, or completed.
progress	number	Progress from 0 to 100.
page_count / current_page	number	Output page count and current scan page.
output_type / output_format	string	Output target type and format.
output_dir	string	Output directory.
export_type	string	single-page or multi-page.
output_path	string	Main output path.
output_paths[]	string[]	All output paths.
last_page_path	string	Most recently saved scanned page path.
assets[]	array	Output assets registered in the local asset service, including url and download_url.
message / error	string	Current message and failure reason.
started_at / updated_at	string	Task timestamps.
cancel_requested	boolean	Whether cancellation was requested.

Scan task event is sane.scan_changed; payload contains task_id, task, and provider.

Request Examples

Get status and list devices:

{ "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 } }

Open a device and set options:

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

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

Save and apply a profile:

{
  "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"
    }
  }
}

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

Submit an image scan task:

{
  "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"
    }
  }
}

Submit a PDF scan task with image enhancement:

{
  "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"
      }
    }
  }
}

Get and cancel a scan task:

{ "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" } }