1Sane(3) User Contributed Perl Documentation Sane(3)
2
6 Sane - Perl extension for the SANE (Scanner Access Now Easy) Project
7
9 use Sane;
10 my @devices = Sane->get_devices;
11 my $device = Sane::Device->open($devices[0]->{name});
12 my $param = $device->get_parameters;
13 $device->write_pnm_header($fh);
14 my ($data, $len) = $device->read ($param->{bytes_per_line});
15 print $fh $data;
16
18 Perl bindings for the SANE (Scanner Access Now Easy) Project. This
19 module allows you to access SANE-compatible scanners in a Perlish and
20 object-oriented way, freeing you from the casting and memory management
21 in C, yet remaining very close in spirit to original API.
22
24 The Sane module allows a Perl developer to use SANE-compatible
25 scanners. Find out more about SANE at <http://www.sane-project.org>.
26 Most methods set $Sane::STATUS, which is overloaded to give either an
28 integer as dictated by the SANE standard, or the the corresponding
29 message, as required.
30 Sane->get_version
32 Returns an array with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions:
33 join('.',Sane->get_version)
35 Sane->get_version_scalar
37 Returns an scalar with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions
38 combined as per the Perl version numbering, i.e. sane 1.0.19 gives
39 1.000019. This allows simple version comparisons.
40 Sane->get_devices
42 This function can be used to query the list of devices that are
43 available. If the function executes successfully, it returns a array
44 of hash references with the devices found. The returned list is
45 guaranteed to remain valid until (a) another call to this function is
46 performed or (b) a call to sane_exit() is performed. This function can
47 be called repeatedly to detect when new devices become available.
48 If argument local_only is true, only local devices are returned
50 (devices directly attached to the machine that SANE is running on). If
51 it is false, the device list includes all remote devices that are
52 accessible to the SANE library.
53 my @devices = Sane->get_devices;
55 if ($Sane::STATUS == SANE_STATUS_GOOD) {
56 print "Name: $devices[0]->{name}\n";
57 print "Vendor: $devices[0]->{vendor}\n";
58 print "Model: $devices[0]->{model}\n";
59 print "Type: $devices[0]->{type}\n";
60 }
61 Sane::Device->open
63 This function is used to establish a connection to a particular device.
64 The name of the device to be opened is passed in argument name. If the
65 call completes successfully, a Sane::Device object is returned. As a
66 special case, specifying a zero-length string as the device requests
67 opening the first available device (if there is such a device).
68 my $device = Sane::Device->open($device_name);
70 Sane::Device->get_option_descriptor
72 This function is used to access option descriptors. The function
73 returns a hash reference with the option descriptor for option number n
74 of the Sane::Device object. Option number 0 is guaranteed to be a
75 valid option. Its value is an integer that specifies the number of
76 options that are available for the Sane::Device object (the count
77 includes option 0). If n is not a valid option index, the function
78 croaks.
79 my $option = $device->get_option_descriptor($n);
81 if ($Sane::STATUS == SANE_STATUS_GOOD) {
82 print "Name: $option->{name}\n";
83 print "Name: $option->{title}\n";
84 print "Name: $option->{desc}\n";
85 print "Name: $option->{type}\n";
86 print "Name: $option->{unit}\n";
87 print "Name: $option->{cap}\n";
88 print "Name: $option->{max_values}\n";
89 print "Name: $option->{constraint_type}\n";
90 }
91 The contents of the name, title, desc, type, unit, cap and
93 constraint_type are as the C API description
94 (<http://www.sane-project.org/html>). There is a further constraint key
95 that either contains an array with the possible option values, or a
96 hash with max, min, and quant keys.
97 The max_values key replaced the size key in the C API, and contains the
99 maximum number of values that the option may contain.
100 Sane::Device->get_option
102 Returns the current value of the selected option.
103 my $value = $device->get_option($n);
105 if ($Sane::STATUS == SANE_STATUS_GOOD) {
106 print "value: $value\n";
107 }
108 For $option->{max_values} > 1, $value is a reference to an array.
110 Sane::Device->set_auto
112 Commands the selected device to automatically select an appropriate
113 value. This mode remains effective until overridden by an explicit
114 set_option request.
115 $device->set_auto($n);
117 Sane::Device->set_option
119 Sets the selected option, returning flags in $info, which are described
120 in the C API (<http://www.sane-project.org/html>).
121 $orig = $device->get_option($n);
123 $info = $device->set_option($n, $value);
124 if ($info & SANE_INFO_INEXACT) {
125 $value = $device->get_option($n);
126 print "rounded value of $opt->{name} from $orig to $value\n";
127 }
128 For $option->{max_values} > 1, $value can be a reference to an array.
130 Sane::Device->get_parameters
132 This function is used to obtain the current scan parameters. The
133 returned parameters are guaranteed to be accurate between the time a
134 scan has been started (Sane::Device->start() has been called) and the
135 completion of that request. Outside of that window, the returned values
136 are best-effort estimates of what the parameters will be when
137 Sane::Device->start() gets invoked. Calling this function before a scan
138 has actually started allows, for example, to get an estimate of how big
139 the scanned image will be.
140 $param = $device->get_parameters;
142 if ($Sane::STATUS == SANE_STATUS_GOOD) {
143 print "format $param->{format}\n";
144 print "last_frame $param->{last_frame}\n";
145 print "bytes_per_line $param->{bytes_per_line}\n";
146 print "pixels_per_line $param->{pixels_per_line}\n";
147 print "lines $param->{lines}\n";
148 print "depth $param->{depth}\n";
149 }
150 Please see the C documentation (<http://www.sane-project.org/html>) for
152 details of the above values.
153 Sane::Device->start
155 This function initiates aquisition of an image from the device
156 specified.
157 $device->start;
159 Sane::Device->read
161 This function is used to read image data from the device specified.
162 The number of bytes returned in $buf is stored in $len. A backend must
163 set this to zero when a status other than SANE_STATUS_GOOD is returned.
164 When the call succeeds, the number of bytes returned can be anywhere in
165 the range from 0 to maxlen bytes.
166 $param = $device->get_parameters;
168 $maxlen = $param->{bytes_per_line};
169 ($buf, $len) = $test->read ($maxlen);
170 If this function is called when no data is available, one of two things
172 may happen, depending on the I/O mode that is in effect for the device.
173 1. If the device is in blocking I/O mode (the default mode), the call
175 blocks until at least one data byte is available (or until some error
176 occurs).
177 2. If the device is in non-blocking I/O mode, the call returns
178 immediately with status SANE_STATUS_GOOD and with $len set to zero.
179 The I/O mode of the device can be set via a call to
181 Sane::Device->set_io_mode().
182 Sane::Device->cancel
184 This function is used to immediately or as quickly as possible cancel
185 the currently pending operation of the device.
186 $device->cancel;
188 This function can be called at any time (as long as $device is valid)
190 but usually affects long-running operations only (such as image is
191 acquisition). It is safe to call this function asynchronously (e.g.,
192 from within a signal handler). It is important to note that completion
193 of this operaton does not imply that the currently pending operation
194 has been cancelled. It only guarantees that cancellation has been
195 initiated. Cancellation completes only when the cancelled call returns
196 (typically with a status value of SANE_STATUS_CANCELLED). Since the
197 SANE API does not require any other operations to be re-entrant, this
198 implies that a frontend must not call any other operation until the
199 cancelled operation has returned.
200 Sane::Device->set_io_mode
202 This function is used to set the I/O mode of the device. The I/O mode
203 can be either blocking or non-blocking. If argument $bool is SANE_TRUE,
204 the mode is set to non-blocking mode, otherwise it's set to blocking
205 mode. This function can be called only after a call to
206 Sane::Device->start() has been performed.
207 $device->set_io_mode ($bool);
209 By default, newly opened handles operate in blocking mode. A backend
211 may elect not to support non-blocking I/O mode. In such a case the
212 status value SANE_STATUS_UNSUPPORTED is returned. Blocking I/O must be
213 supported by all backends, so calling this function with SANE_FALSE is
214 guaranteed to complete successfully.
215 Sane::Device->get_select_fd
217 This function is used to obtain a (platform-specific) file-descriptor
218 for the device that is readable if and only if image data is available
219 (i.e., when a call to Sane::Device->read() will return at least one
220 byte of data).
221 $fd = $device->get_select_fd;
223 This function can be called only after a call to Sane::Device->start()
225 has been performed and the returned file-descriptor is guaranteed to
226 remain valid for the duration of the current image acquisition (i.e.,
227 until Sane::Device->cancel() or Sane::Device->start() get called again
228 or until Sane::Device->read() returns with status SANE_STATUS_EOF).
229 Indeed, a backend must guarantee to close the returned select file
230 descriptor at the point when the next Sane::Device->read() call would
231 return SANE_STATUS_EOF. This is necessary to ensure the application can
232 detect when this condition occurs without actually having to call
233 Sane::Device->read().
234 A backend may elect not to support this operation. In such a case, the
236 function returns with status code SANE_STATUS_UNSUPPORTED.
237 Note that the only operation supported by the returned file-descriptor
239 is a host operating-system dependent test whether the file-descriptor
240 is readable (e.g., this test can be implemented using select() or
241 poll() under UNIX). If any other operation is performed on the file
242 descriptor, the behavior of the backend becomes unpredictable. Once
243 the file-descriptor signals ``readable'' status, it will remain in that
244 state until a call to sane_read() is performed. Since many input
245 devices are very slow, support for this operation is strongly
246 encouraged as it permits an application to do other work while image
247 acquisition is in progress.
248 Sane::Device->write_pnm_header
250 This function is a pure-Perl helper function to write a PNM header. It
251 will fetch the current image settings using
252 Sane::Device->get_parameters, if they are not already provided, e.g.:
253 $device->write_pnm_header($fh);
255 or
257 $parm = $device->get_parameters;
259 $device->write_pnm_header ($fh, $parm->{format},
260 $parm->{pixels_per_line},
261 $parm->{lines}, $parm->{depth});
262
264 The SANE Standard Reference <http://www.sane-project.org/html> is a
265 handy companion. The Perl bindings follow the C API very closely, and
266 the C reference documentation should be considered the canonical
267 source.
268
270 Jeffrey Ratcliffe, <Jeffrey.Ratcliffe@gmail.com>
271
273 Copyright (C) 2008--2012 by Jeffrey Ratcliffe
274 This library is free software; you can redistribute it and/or modify it
276 under the same terms as Perl itself, either Perl version 5.8.5 or, at
277 your option, any later version of Perl 5 you may have available.
278perl v5.36.0 2022-07-22 Sane(3)