Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Image::Sane(3)	      User Contributed Perl Documentation	Image::Sane(3)

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.

perl v5.32.1			  2019-11-15			Image::Sane(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SUBROUTINES/METHODS | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | DEPENDENCIES | INCOMPATIBILITIES | BUGS AND LIMITATIONS | SEE ALSO | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Image::Sane&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help