1Image::Sane(3) User Contributed Perl Documentation Image::Sane(3)
2
6 Image::Sane - Perl extension for the SANE (Scanner Access Now Easy)
7 Project
8
10 5
11
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
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 Find out more about SANE at <http://www.sane-project.org>.
28
30 Image::Sane->get_version
31 Returns an array with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions:
32 join('.', Image::Sane->get_version)
34 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 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 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 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 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 my $device = Image::Sane::Device->open($device_name);
73 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 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 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 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 Image::Sane::Device->get_option
108 Returns the current value of the selected option.
109 try {
111 $value = $device->get_option($n);
112 print "value: $value\n";
113 }
114 catch {
115 print "Error getting option:", $_->error, "\n";
116 };
117 For $option->{max_values} > 1, $value is a reference to an array.
119 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 $device->set_auto($n);
126 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 $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 For $option->{max_values} > 1, $value can be a reference to an array.
139 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 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 Please see the C documentation (<http://www.sane-project.org/html>) for
164 details of the above values.
165 Image::Sane::Device->start
167 This function initiates acquisition of an image from the device
168 specified.
169 $device->start;
171 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 $param = $device->get_parameters;
180 $maxlen = $param->{bytes_per_line};
181 ($buf, $len) = $test->read ($maxlen);
182 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 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 The I/O mode of the device can be set via a call to
193 Image::Sane::Device->set_io_mode().
194 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 $device->cancel;
200 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 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 $device->set_io_mode ($bool);
221 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 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 $fd = $device->get_select_fd;
235 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 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 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 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 $device->write_pnm_header($fh);
270 or
272 $parm = $device->get_parameters;
274 $device->write_pnm_header ($fh, $parm->{format},
275 $parm->{pixels_per_line},
276 $parm->{lines}, $parm->{depth});
277
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
286 This module does not require any special configuration or environment,
287 beyond that needed for Perl and SANE.
288
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
296 None known.
297
299 None known.
300
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
308 Jeffrey Ratcliffe, <jffry@posteo.net>
309
311 Copyright (C) 2008--2019 by Jeffrey Ratcliffe
312 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.
316perl v5.38.0 2023-07-20 Image::Sane(3)