Scanner Access For Tcl

Home

Documentation

Download / Install

Development

saft

NAME
SYNOPSIS
DESCRIPTION
COMMANDS
BLOCKING VS. NONBLOCKING INVOCATION
IMAGE FILE NUMBERS
DEVICE INFORMATION DICTIONARY
OPTIONS DICTIONARY
SCAN INFO DICTIONARY
BUGS
SEE ALSO
KEYWORDS

NAME

saft - scanner acces for Tcl.

SYNOPSIS

package require Tcl 8.5

package require saft ?0.1?

::saft::searchScanners ?commandPrefix?

::saft::listScannerInfo subcommand ?UID ?option? ?

::saft::startScan ?options? filename

DESCRIPTION

saft is a scanning utility for Tcl that tries to provide a common interface to different scanning subsystems. Currently only Sane is supported.

COMMANDS

::saft::searchScanners ?-command commandPrefix?

Search for connected scanners and collect information about the options each of them supports. These informations are saved interally and can be queried with ::saft::listScannerInfo.

Note that saft does not autodetect connection/disconnection of devices: ::saft::searchScanners needs to be called to make a new device available or to remove information about a disconnected device.

If the -command option is passed, the command runs in "nonblocking" mode. This means that the command will return immediately and arrange for commandPrefix to be invoked when the operation is completed. The result of the device search will be appended as one additional argument to commandPrefix. Whtout the -command option, the command returns only once the operation is complete ("blocking" mode). See also BLOCKING VS. NONBLOCKING INVOCATION below.

The command returns the result of the device search in blocking mode, empty string in nonblocking. The result is a list of device dictionaries, one for each device found (see DEVICE INFORMATION DICTIONARY below).

::saft::listScannerInfo subcommand ?UID ?option? ?

Retrieve various information about scanning devices, i.e. available devices, accepted values for options, defaults, etc.

This command returns internally saved information, which might not reflect the actual state of the system. If the system changed (e.g. new device plugged/unplugged), saft::searchScanners must be called before those changes can be seen with this command.

::saft::listScannerInfo will raise an error if it is called while searchScanners is running in the background. This is because information gotten while ::saft::searchScanners is running in the background might become invalid as soon as the search completes.

See the sections DEVICE INFORMATION and OPTIONS DICTIONARY for detailed information about the format of the dictionaries returned by this command.

Following subcommands are acceppted:

::saft::listScannerInfo default ?UID ?option? ?

With no additional arguments, returns a device dictionary describing the default scanning device. If no devices are present, or if ::saft::searchScanners has not been invoked yet, the dictionary will have empty strings as values for each key.

If an UID is provided, returns the defaults for scanner-specific options as an options dictionary.

If an option argument is passed (must be one of the scanner-specific options) the command returns the default for that option.

An empty string means that the option is not supported by the device.

::saft::listScannerInfo available ?UID ?option? ?

With no additional arguments, returns a list of device dictionaries. Each of these dictionaries describes one of the available scanning devices. If no devices are present, or if ::saft::searchScanners has not been invoked yet, returns an empty list.

If an UID is provided, provides all acceppted values for scanner-specific options in an options dictionary. For each option, this dictionary will contain a list of supported values.

If an option argument is passed (must be one of the scanner-specific options) the command returns a list containig the available values for that option.

An empty list means that the option is not supported by that specific device.

::saft::startScan ?options? filename

Start to scan an image and write it to filename. The path to the file must exist - no directories will be created.

This command can be invoked in "nonblocking" mode (providing a -command option) or in "blocking" mode (the default). In "nonblocking" mode, the command returns an empty string. In "blocking" mode it returns a list of dictionaries - one for each page scanned. Each dictionary contains the parameters used for the scan. More details about this dictionary can be found in the section SCAN INFO DICTIONARY. For details about "blocking" vs. "nonblocking" operation see BLOCKING VS. NONBLOCKING INVOCATION.

filename specifies where the scanned image will be written. Every occurrence of the sequence %N in filename will be substituted with an numeric index. See IMAGE FILE NUMBERS below.

::saft::startScan accepts a number of options to control the scanning operation. They can be split in two categories: device-dependent and device-independent ones. The device-independent options can always be used, no matter what device is used. They are:
-command commandPrefix

If this option is specified, the command returns immediately and arranges commandPrefix to be invoked when the scanning of a page is complete. One argument will be appended to commandPrefix, a dictionary containig detailed information about the scan (see SCAN INFO DICTIONARY below). When scanning from an automatic document feeder, the command will be invoked once for every page scanned.

-device UID

Use scanner with identifier UID. If not specified, the default device will be used.

-maxpages number

When scanning from the automatic document feeder, scan at most number pages. Empty string or negative values mean no maximum set, i.e. scan util feeder is out of documents. Defaults to -1 (scan everything). Option is ignored when no automatic document feeder is used.

-overwrite boolean

If true, overwrite existing files when scanning. Default: false.

-startindex int

First index to use when output file(s) are numbered (see IMAGE FILE NUMBERS below).

Device-dependent options might or mith not be supported by a given device. The available and default values for these options vary with devices and platform. A list of valid values and defaults can be obtained with the ::saft::listScannerInfo command. For reliable behaviour, you MUST check the available values for these options before using them. Passing invalid values and using options that the device does not support, results in an error.
-colordepth descr

Color depth (mode) to use. descr is subsystem/scanner-specific, and must be one of the options listed by saft::getInformation

-format formatName

Image format to use. formatName is the standard extension of the desired image format (without the dot).

-resolution int

Resolution to use. If specified resolution is not supported, the nearest one is used.

-source source

Select the scan source (e.g. ADF, Flatbed).

BLOCKING VS. NONBLOCKING INVOCATION

The commands ::saft::searchScanners and ::saft::startScan can take quite a while to complete. If you need to keep your application responsive they can be used in "nonblocking" mode. Both commands accept a -command option. If this option is given, the command returns immediately. The return value is an empty string in this case. When the requested task is complete, the commandPrefix passed with -command will be invoked - with the result of the operation appended to it.

If no -command option is provided, the commands runs in "blocking" mode, i.e. they return only once the operation is complete. In this case the return value is the result of the operation.

IMAGE FILE NUMBERS

An index can be added to the name of the scanned files, useful when scanning multiple pages with an automatic document feeder. This index will be increased for each successive page in one scan operation. The index is not remembered from one call to ::saft::startScan to the next.

An index will be added when at least one of the following occurs:

Every occurrence of the sequence %N in filename will be replaced with the index. %% will be substituted with a single ’%’, all other %* sequences - where * is any characther - will be ignored. The %N can be used in directory names too, but beware: the path must already exist!

If an index is needed but no ’%N’ can be found in the filename, the index will be placed at the end of the name of the file, before the extension (path/to/filename%N.ext).

If an index is required, but -startindex was not provided, index count starts with 1.

DEVICE INFORMATION DICTIONARY

Information about scanners is passed as a dictionary with this these key/values:
description text

A human readable (and understandable...) text description of the device. Typically vendor and model.

device devString

The OS-specific name for the device - e.g. ‘brother3:bus2;dev5’ under Sane/Linux. Nothe that, from one session to the other, this name can be different for the same actual device. Ergo, if you want to remember a specific device between sessions - for example to save a default scanner - don’t use devString! Use UID for this purpose.

UID identifier

A unique identifier for the device. The actual format of this identifier is not defined, but on a given subsystem/platform a device will always have the same UID.

OPTIONS DICTIONARY

Information about scanner-specific options is passed in a dictionary. This dictionary will have a key for every scanner-specific option, the corresponding value is either a list (supported values) or a single value (current setting, defaults).

SCAN INFO DICTIONARY

A scan operation will produce a dictionary containig detailed information about options and parameters used for the scan. The values in this dictionary are the ones actually used, which are not necessarly equal to the ones passed to the command. The dictionary has these elements:
errcode code

This key signals if everything went smoothly: it is strongly recommended to check code before doing anything with the other values. If there was a problem, they might be meaningless. These error codes (strings, actually) are meant to be interpreted at program level - they tell what went wrong. A human readable message is stored in errmsg. Possible values are:

FILEPERM

Cannot write output file

NODOCUMENT

No document available - nothing was scanned.

NOSCANNER

Device specified with -device option or default device not found or no scanners at all.

SUBSYSTEM

Problem with the platform-specific subsystem: missing dependency/unsupported version, other problem accessing device.

errmsg message

Error message in prosa. Empty string if command was sucessful.

colordepth depthString

Color depth used.

command commandPrefix

Command prefix passed.

device UID

UID of device that performed the scan

file fileName

The absolute and normalized path to the image file scanned.

format formatName

Image format used for output

lastpage boolean

If false, the scan operation will produce at least one more page. True signals the end of the scanning process.

maxpages

Value of -maxpages passed.

pagecount int

The number of pages scanned so far.

resolution int

Resolution used for the scan

startindex int

If an index was substituted in the filename(s), the index of the first page. Empty string otherwise.

source scanSource

Scanner source used.

BUGS

This is an early development release, so there are certainly many bugs and problems. Please report!

Please post bug reports, whishes, suggestions to the mailing list or the bugtracker on the saft project page at sourceforge: http://sourceforge.net/projects/saftcl/

SEE ALSO

scanimage(1) sane(7)

KEYWORDS

scan image scanner sane

Contact | Hosting: | | Last updated: May 2013