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

NAME

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

SYNOPSIS

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

ABSTRACT

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

DESCRIPTION

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
27       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
31   Sane->get_version
32       Returns an array with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions:
33
34         join('.',Sane->get_version)
35
36   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
41   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
49       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
54         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
62   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
69         my $device = Sane::Device->open($device_name);
70
71   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
80         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
92       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
98       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
101   Sane::Device->get_option
102       Returns the current value of the selected option.
103
104         my $value = $device->get_option($n);
105         if ($Sane::STATUS == SANE_STATUS_GOOD) {
106          print "value: $value\n";
107         }
108
109       For $option->{max_values} > 1, $value is a reference to an array.
110
111   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
116         $device->set_auto($n);
117
118   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
122         $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
129       For $option->{max_values} > 1, $value can be a reference to an array.
130
131   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
141         $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
151       Please see the C documentation (<http://www.sane-project.org/html>) for
152       details of the above values.
153
154   Sane::Device->start
155       This function initiates aquisition of an image from the device
156       specified.
157
158         $device->start;
159
160   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
167         $param = $device->get_parameters;
168         $maxlen = $param->{bytes_per_line};
169         ($buf, $len) = $test->read ($maxlen);
170
171       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
174       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
180       The I/O mode of the device can be set via a call to
181       Sane::Device->set_io_mode().
182
183   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
187         $device->cancel;
188
189       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
201   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
208         $device->set_io_mode ($bool);
209
210       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
216   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
222         $fd = $device->get_select_fd;
223
224       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
235       A backend may elect not to support this operation. In such a case, the
236       function returns with status code SANE_STATUS_UNSUPPORTED.
237
238       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
249   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
254        $device->write_pnm_header($fh);
255
256       or
257
258        $parm = $device->get_parameters;
259        $device->write_pnm_header ($fh, $parm->{format},
260                                        $parm->{pixels_per_line},
261                                        $parm->{lines}, $parm->{depth});
262

SEE ALSO

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

AUTHOR

270       Jeffrey Ratcliffe, <Jeffrey.Ratcliffe@gmail.com>
271
273       Copyright (C) 2008--2012 by Jeffrey Ratcliffe
274
275       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.
278
279
280
281perl v5.34.0                      2022-01-21                           Sane(3)
Impressum