Provided by: libimage-sane-perl_5-2build3_amd64 bug

NAME

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

VERSION

       5

SYNOPSIS

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

DESCRIPTION

       These Perl bindings for the SANE (Scanner Access Now Easy) Project allow you to access
       SANE-compatible scanners in a Perlish and object-oriented way, freeing you from the
       casting and memory management in C, yet remaining very close in spirit to original API.

       Find out more about SANE at <http://www.sane-project.org>.

SUBROUTINES/METHODS

   Image::Sane->get_version
       Returns an array with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions:

         join('.', Image::Sane->get_version)

   Image::Sane->get_version_scalar
       Returns an scalar with the SANE_VERSION_(MAJOR|MINOR|BUILD) versions combined as per the
       Perl version numbering, i.e. sane 1.0.19 gives 1.000019. This allows simple version
       comparisons.

   Image::Sane->get_devices
       This function can be used to query the list of devices that are available.  If the
       function executes successfully, it returns a array of hash references with the devices
       found.  The returned list is guaranteed to remain valid until (a) another call to this
       function is performed or (b) a call to sane_exit() is performed.  This function can be
       called repeatedly to detect when new devices become available.

       If argument local_only is true, only local devices are returned (devices directly attached
       to the machine that SANE is running on).  If it is false, the device list includes all
       remote devices that are accessible to the SANE library.

         try {
             @devices = Image::Sane->get_devices;
             print "Name: $devices[0]->{name}\n";
             print "Vendor: $devices[0]->{vendor}\n";
             print "Model: $devices[0]->{model}\n";
             print "Type: $devices[0]->{type}\n";
         }
         catch {
             print "Error getting devices:", $_->error, "\n";
         };

   Image::Sane::Device->open
       This function is used to establish a connection to a particular device.  The name of the
       device to be opened is passed in argument name.  If the call completes successfully, a
       Image::Sane::Device object is returned.  As a special case, specifying a zero-length
       string as the device requests opening the first available device (if there is such a
       device).

         my $device = Image::Sane::Device->open($device_name);

   Image::Sane::Device->get_option_descriptor
       This function is used to access option descriptors.  The function returns a hash reference
       with the option descriptor for option number n of the Image::Sane::Device object.  Option
       number 0 is guaranteed to be a valid option.  Its value is an integer that specifies the
       number of options that are available for the Image::Sane::Device object (the count
       includes option 0). If n is not a valid option index, the function croaks.

         try {
             $option = $device->get_option_descriptor($n);
             print "Name: $option->{name}\n";
             print "Name: $option->{title}\n";
             print "Name: $option->{desc}\n";
             print "Name: $option->{type}\n";
             print "Name: $option->{unit}\n";
             print "Name: $option->{cap}\n";
             print "Name: $option->{max_values}\n";
             print "Name: $option->{constraint_type}\n";
         }
         catch {
             print "Error getting option descriptor:", $_->error, "\n";
         };

       The contents of the hash keys "name", "title", "desc", "type", "unit", "cap" and
       "constraint_type" are as per the C API description (<http://www.sane-project.org/html>).
       There is a further constraint key that either contains an array with the possible option
       values, or a hash with keys "max", "min", and "quant".

       The max_values key replaced the size key in the C API, and contains the maximum number of
       values that the option may contain.

   Image::Sane::Device->get_option
       Returns the current value of the selected option.

         try {
             $value = $device->get_option($n);
             print "value: $value\n";
         }
         catch {
             print "Error getting option:", $_->error, "\n";
         };

       For $option->{max_values} > 1, $value is a reference to an array.

   Image::Sane::Device->set_auto
       Commands the selected device to automatically select an appropriate value.  This mode
       remains effective until overridden by an explicit set_option request.

         $device->set_auto($n);

   Image::Sane::Device->set_option
       Sets the selected option, returning flags in $info, which are described in the C API
       (<http://www.sane-project.org/html>).

         $orig = $device->get_option($n);
         $info = $device->set_option($n, $value);
         if ($info & SANE_INFO_INEXACT) {
          $value = $device->get_option($n);
          print "rounded value of $opt->{name} from $orig to $value\n";
         }

       For $option->{max_values} > 1, $value can be a reference to an array.

   Image::Sane::Device->get_parameters
       This function is used to obtain the current scan parameters.  The returned parameters are
       guaranteed to be accurate between the time a scan has been started
       (Image::Sane::Device->start() has been called) and the completion of that request. Outside
       of that window, the returned values are best-effort estimates of what the parameters will
       be when Image::Sane::Device->start() gets invoked. Calling this function before a scan has
       actually started allows, for example, to get an estimate of how big the scanned image will
       be.

         try {
             $param = $device->get_parameters;
             print "format $param->{format}\n";
             print "last_frame $param->{last_frame}\n";
             print "bytes_per_line $param->{bytes_per_line}\n";
             print "pixels_per_line $param->{pixels_per_line}\n";
             print "lines $param->{lines}\n";
             print "depth $param->{depth}\n";
         }
         catch {
             print "Error getting parameters:", $_->error, "\n";
         };

       Please see the C documentation (<http://www.sane-project.org/html>) for details of the
       above values.

   Image::Sane::Device->start
       This function initiates acquisition of an image from the device specified.

         $device->start;

   Image::Sane::Device->read
       This function is used to read image data from the device specified.  The number of bytes
       returned in $buf is stored in $len.  A backend must set this to zero when an error is
       thrown.  if the call succeeds, the number of bytes returned can be anywhere in the range
       from 0 to $maxlen bytes.

         $param = $device->get_parameters;
         $maxlen = $param->{bytes_per_line};
         ($buf, $len) = $test->read ($maxlen);

       If this function is called when no data is available, one of two things may happen,
       depending on the I/O mode that is in effect for the device.

       1. If the device is in blocking I/O mode (the default mode), the call blocks until at
       least one data byte is available (or until some error occurs).
       2. If the device is in non-blocking I/O mode, the call returns immediately with $len set
       to zero.

       The I/O mode of the device can be set via a call to Image::Sane::Device->set_io_mode().

   Image::Sane::Device->cancel
       This function is used to immediately or as quickly as possible cancel the currently
       pending operation of the device.

         $device->cancel;

       This function can be called at any time (as long as $device is valid) but usually affects
       long-running operations only (such as image is acquisition). It is safe to call this
       function asynchronously (e.g., from within a signal handler). It is important to note that
       completion of this operation does not imply that the currently pending operation has been
       cancelled. It only guarantees that cancellation has been initiated. Cancellation completes
       only when the cancelled call throws an exception (typically with a status value of
       SANE_STATUS_CANCELLED).  Since the SANE API does not require any other operations to be
       re-entrant, this implies that a frontend must not call any other operation until the
       cancelled operation has returned.

   Image::Sane::Device->set_io_mode
       This function is used to set the I/O mode of the device. The I/O mode can be either
       blocking or non-blocking. If argument $bool is SANE_TRUE, the mode is set to non-blocking
       mode, otherwise it's set to blocking mode. This function can be called only after a call
       to Image::Sane::Device->start() has been performed.

         $device->set_io_mode ($bool);

       By default, newly opened handles operate in blocking mode. A backend may elect not to
       support non-blocking I/O mode. In such a case the call throws an exception with the status
       value SANE_STATUS_UNSUPPORTED. Blocking I/O must be supported by all backends, so calling
       this function with SANE_FALSE is guaranteed to complete successfully.

   Image::Sane::Device->get_select_fd
       This function is used to obtain a (platform-specific) file-descriptor for the device that
       is readable if and only if image data is available (i.e., when a call to
       Image::Sane::Device->read() will return at least one byte of data).

         $fd = $device->get_select_fd;

       This function can be called only after a call to Image::Sane::Device->start() has been
       performed and the returned file-descriptor is guaranteed to remain valid for the duration
       of the current image acquisition (i.e., until Image::Sane::Device->cancel() or
       Image::Sane::Device->start() is called again or until Image::Sane::Device->read() throws
       an exception with status SANE_STATUS_EOF).  Indeed, a backend must guarantee to close the
       returned select file descriptor at the point when the next Image::Sane::Device->read()
       call would throw an exception with SANE_STATUS_EOF. This is necessary to ensure the
       application can detect when this condition occurs without actually having to call
       Image::Sane::Device->read().

       A backend may elect not to support this operation. In such a case, the function throws an
       exception with status code SANE_STATUS_UNSUPPORTED.

       Note that the only operation supported by the returned file-descriptor is a host
       operating-system dependent test whether the file-descriptor is readable (e.g., this test
       can be implemented using select() or poll() under UNIX). If any other operation is
       performed on the file descriptor, the behaviour of the backend becomes unpredictable.
       Once the file-descriptor signals ``readable'' status, it will remain in that state until a
       call to sane_read() is performed. Since many input devices are very slow, support for this
       operation is strongly encouraged as it permits an application to do other work while image
       acquisition is in progress.

   Image::Sane::Device->write_pnm_header
       This function is a pure-Perl helper function to write a PNM header. It will fetch the
       current image settings using Image::Sane::Device->get_parameters, if they are not already
       provided, e.g.:

        $device->write_pnm_header($fh);

       or

        $parm = $device->get_parameters;
        $device->write_pnm_header ($fh, $parm->{format},
                                        $parm->{pixels_per_line},
                                        $parm->{lines}, $parm->{depth});

DIAGNOSTICS

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

CONFIGURATION AND ENVIRONMENT

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

DEPENDENCIES

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

INCOMPATIBILITIES

       None known.

BUGS AND LIMITATIONS

       None known.

SEE ALSO

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

AUTHOR

       Jeffrey Ratcliffe, <jffry@posteo.net>

LICENSE AND COPYRIGHT

       Copyright (C) 2008--2019 by Jeffrey Ratcliffe

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of
       Perl 5 you may have available.