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