1Image::Sane(3)        User Contributed Perl Documentation       Image::Sane(3)
2
3
4

NAME

6       Image::Sane - Perl extension for the SANE (Scanner Access Now Easy)
7       Project
8

VERSION

10       5
11

SYNOPSIS

13         use Image::Sane;
14         my @devices = Image::Sane->get_devices;
15         my $device = Image::Sane::Device->open($devices[0]->{name});
16         my $param = $device->get_parameters;
17         $device->write_pnm_header($fh, $param);
18         my ($data, $len) = $device->read ($param->{bytes_per_line});
19         print $fh $data;
20

DESCRIPTION

22       These Perl bindings for the SANE (Scanner Access Now Easy) Project
23       allow you to access SANE-compatible scanners in a Perlish and object-
24       oriented way, freeing you from the casting and memory management in C,
25       yet remaining very close in spirit to original API.
26
27       Find out more about SANE at <http://www.sane-project.org>.
28

SUBROUTINES/METHODS

30   Image::Sane->get_version
31       Returns an array with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions:
32
33         join('.', Image::Sane->get_version)
34
35   Image::Sane->get_version_scalar
36       Returns an scalar with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions
37       combined as per the Perl version numbering, i.e. sane 1.0.19 gives
38       1.000019. This allows simple version comparisons.
39
40   Image::Sane->get_devices
41       This function can be used to query the list of devices that are
42       available.  If the function executes successfully, it returns a array
43       of hash references with the devices found.  The returned list is
44       guaranteed to remain valid until (a) another call to this function is
45       performed or (b) a call to sane_exit() is performed.  This function can
46       be called repeatedly to detect when new devices become available.
47
48       If argument local_only is true, only local devices are returned
49       (devices directly attached to the machine that SANE is running on).  If
50       it is false, the device list includes all remote devices that are
51       accessible to the SANE library.
52
53         try {
54             @devices = Image::Sane->get_devices;
55             print "Name: $devices[0]->{name}\n";
56             print "Vendor: $devices[0]->{vendor}\n";
57             print "Model: $devices[0]->{model}\n";
58             print "Type: $devices[0]->{type}\n";
59         }
60         catch {
61             print "Error getting devices:", $_->error, "\n";
62         };
63
64   Image::Sane::Device->open
65       This function is used to establish a connection to a particular device.
66       The name of the device to be opened is passed in argument name.  If the
67       call completes successfully, a Image::Sane::Device object is returned.
68       As a special case, specifying a zero-length string as the device
69       requests opening the first available device (if there is such a
70       device).
71
72         my $device = Image::Sane::Device->open($device_name);
73
74   Image::Sane::Device->get_option_descriptor
75       This function is used to access option descriptors.  The function
76       returns a hash reference with the option descriptor for option number n
77       of the Image::Sane::Device object.  Option number 0 is guaranteed to be
78       a valid option.  Its value is an integer that specifies the number of
79       options that are available for the Image::Sane::Device object (the
80       count includes option 0). If n is not a valid option index, the
81       function croaks.
82
83         try {
84             $option = $device->get_option_descriptor($n);
85             print "Name: $option->{name}\n";
86             print "Name: $option->{title}\n";
87             print "Name: $option->{desc}\n";
88             print "Name: $option->{type}\n";
89             print "Name: $option->{unit}\n";
90             print "Name: $option->{cap}\n";
91             print "Name: $option->{max_values}\n";
92             print "Name: $option->{constraint_type}\n";
93         }
94         catch {
95             print "Error getting option descriptor:", $_->error, "\n";
96         };
97
98       The contents of the hash keys "name", "title", "desc", "type", "unit",
99       "cap" and "constraint_type" are as per the C API description
100       (<http://www.sane-project.org/html>). There is a further constraint key
101       that either contains an array with the possible option values, or a
102       hash with keys "max", "min", and "quant".
103
104       The max_values key replaced the size key in the C API, and contains the
105       maximum number of values that the option may contain.
106
107   Image::Sane::Device->get_option
108       Returns the current value of the selected option.
109
110         try {
111             $value = $device->get_option($n);
112             print "value: $value\n";
113         }
114         catch {
115             print "Error getting option:", $_->error, "\n";
116         };
117
118       For $option->{max_values} > 1, $value is a reference to an array.
119
120   Image::Sane::Device->set_auto
121       Commands the selected device to automatically select an appropriate
122       value.  This mode remains effective until overridden by an explicit
123       set_option request.
124
125         $device->set_auto($n);
126
127   Image::Sane::Device->set_option
128       Sets the selected option, returning flags in $info, which are described
129       in the C API (<http://www.sane-project.org/html>).
130
131         $orig = $device->get_option($n);
132         $info = $device->set_option($n, $value);
133         if ($info & SANE_INFO_INEXACT) {
134          $value = $device->get_option($n);
135          print "rounded value of $opt->{name} from $orig to $value\n";
136         }
137
138       For $option->{max_values} > 1, $value can be a reference to an array.
139
140   Image::Sane::Device->get_parameters
141       This function is used to obtain the current scan parameters.  The
142       returned parameters are guaranteed to be accurate between the time a
143       scan has been started (Image::Sane::Device->start() has been called)
144       and the completion of that request. Outside of that window, the
145       returned values are best-effort estimates of what the parameters will
146       be when Image::Sane::Device->start() gets invoked. Calling this
147       function before a scan has actually started allows, for example, to get
148       an estimate of how big the scanned image will be.
149
150         try {
151             $param = $device->get_parameters;
152             print "format $param->{format}\n";
153             print "last_frame $param->{last_frame}\n";
154             print "bytes_per_line $param->{bytes_per_line}\n";
155             print "pixels_per_line $param->{pixels_per_line}\n";
156             print "lines $param->{lines}\n";
157             print "depth $param->{depth}\n";
158         }
159         catch {
160             print "Error getting parameters:", $_->error, "\n";
161         };
162
163       Please see the C documentation (<http://www.sane-project.org/html>) for
164       details of the above values.
165
166   Image::Sane::Device->start
167       This function initiates acquisition of an image from the device
168       specified.
169
170         $device->start;
171
172   Image::Sane::Device->read
173       This function is used to read image data from the device specified.
174       The number of bytes returned in $buf is stored in $len.  A backend must
175       set this to zero when an error is thrown.  if the call succeeds, the
176       number of bytes returned can be anywhere in the range from 0 to $maxlen
177       bytes.
178
179         $param = $device->get_parameters;
180         $maxlen = $param->{bytes_per_line};
181         ($buf, $len) = $test->read ($maxlen);
182
183       If this function is called when no data is available, one of two things
184       may happen, depending on the I/O mode that is in effect for the device.
185
186       1. If the device is in blocking I/O mode (the default mode), the call
187       blocks until at least one data byte is available (or until some error
188       occurs).
189       2. If the device is in non-blocking I/O mode, the call returns
190       immediately with $len set to zero.
191
192       The I/O mode of the device can be set via a call to
193       Image::Sane::Device->set_io_mode().
194
195   Image::Sane::Device->cancel
196       This function is used to immediately or as quickly as possible cancel
197       the currently pending operation of the device.
198
199         $device->cancel;
200
201       This function can be called at any time (as long as $device is valid)
202       but usually affects long-running operations only (such as image is
203       acquisition). It is safe to call this function asynchronously (e.g.,
204       from within a signal handler). It is important to note that completion
205       of this operation does not imply that the currently pending operation
206       has been cancelled. It only guarantees that cancellation has been
207       initiated. Cancellation completes only when the cancelled call throws
208       an exception (typically with a status value of SANE_STATUS_CANCELLED).
209       Since the SANE API does not require any other operations to be re-
210       entrant, this implies that a frontend must not call any other operation
211       until the cancelled operation has returned.
212
213   Image::Sane::Device->set_io_mode
214       This function is used to set the I/O mode of the device. The I/O mode
215       can be either blocking or non-blocking. If argument $bool is SANE_TRUE,
216       the mode is set to non-blocking mode, otherwise it's set to blocking
217       mode. This function can be called only after a call to
218       Image::Sane::Device->start() has been performed.
219
220         $device->set_io_mode ($bool);
221
222       By default, newly opened handles operate in blocking mode. A backend
223       may elect not to support non-blocking I/O mode. In such a case the call
224       throws an exception with the status value SANE_STATUS_UNSUPPORTED.
225       Blocking I/O must be supported by all backends, so calling this
226       function with SANE_FALSE is guaranteed to complete successfully.
227
228   Image::Sane::Device->get_select_fd
229       This function is used to obtain a (platform-specific) file-descriptor
230       for the device that is readable if and only if image data is available
231       (i.e., when a call to Image::Sane::Device->read() will return at least
232       one byte of data).
233
234         $fd = $device->get_select_fd;
235
236       This function can be called only after a call to
237       Image::Sane::Device->start() has been performed and the returned file-
238       descriptor is guaranteed to remain valid for the duration of the
239       current image acquisition (i.e., until Image::Sane::Device->cancel() or
240       Image::Sane::Device->start() is called again or until
241       Image::Sane::Device->read() throws an exception with status
242       SANE_STATUS_EOF).  Indeed, a backend must guarantee to close the
243       returned select file descriptor at the point when the next
244       Image::Sane::Device->read() call would throw an exception with
245       SANE_STATUS_EOF. This is necessary to ensure the application can detect
246       when this condition occurs without actually having to call
247       Image::Sane::Device->read().
248
249       A backend may elect not to support this operation. In such a case, the
250       function throws an exception with status code SANE_STATUS_UNSUPPORTED.
251
252       Note that the only operation supported by the returned file-descriptor
253       is a host operating-system dependent test whether the file-descriptor
254       is readable (e.g., this test can be implemented using select() or
255       poll() under UNIX). If any other operation is performed on the file
256       descriptor, the behaviour of the backend becomes unpredictable.  Once
257       the file-descriptor signals ``readable'' status, it will remain in that
258       state until a call to sane_read() is performed. Since many input
259       devices are very slow, support for this operation is strongly
260       encouraged as it permits an application to do other work while image
261       acquisition is in progress.
262
263   Image::Sane::Device->write_pnm_header
264       This function is a pure-Perl helper function to write a PNM header. It
265       will fetch the current image settings using
266       Image::Sane::Device->get_parameters, if they are not already provided,
267       e.g.:
268
269        $device->write_pnm_header($fh);
270
271       or
272
273        $parm = $device->get_parameters;
274        $device->write_pnm_header ($fh, $parm->{format},
275                                        $parm->{pixels_per_line},
276                                        $parm->{lines}, $parm->{depth});
277

DIAGNOSTICS

279       If the underlying SANE library returns a status value other than
280       SANE_STATUS_GOOD, an exception is thrown. It is therefore suggested
281       that these are caught using the Try::Tiny module. $_->status and
282       $_->error can be used within the catch{} clause to give the status code
283       and its equivalent string.
284

CONFIGURATION AND ENVIRONMENT

286       This module does not require any special configuration or environment,
287       beyond that needed for Perl and SANE.
288

DEPENDENCIES

290       Obviously, the SANE library is required, together with the backends for
291       the scanners to be used.
292       Exception::Class is used for throwing exceptions. It is suggested that
293       these are caught with Try::Tiny.
294

INCOMPATIBILITIES

296       None known.
297

BUGS AND LIMITATIONS

299       None known.
300

SEE ALSO

302       The SANE Standard Reference <http://www.sane-project.org/html> is a
303       handy companion. The Perl bindings follow the C API very closely, and
304       the C reference documentation should be considered the canonical
305       source.
306

AUTHOR

308       Jeffrey Ratcliffe, <jffry@posteo.net>
309
311       Copyright (C) 2008--2019 by Jeffrey Ratcliffe
312
313       This library is free software; you can redistribute it and/or modify it
314       under the same terms as Perl itself, either Perl version 5.8.5 or, at
315       your option, any later version of Perl 5 you may have available.
316
317
318
319perl v5.38.0                      2023-07-20                    Image::Sane(3)
Impressum