.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Sane 3pm" .TH Sane 3pm "2012-04-02" "perl v5.20.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Sane \- Perl extension for the SANE (Scanner Access Now Easy) Project .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 7 \& use Sane; \& my @devices = Sane\->get_devices; \& my $device = Sane::Device\->open($devices[0]\->{name}); \& my $param = $device\->get_parameters; \& $device\->write_pnm_header($fh); \& my ($data, $len) = $device\->read ($param\->{bytes_per_line}); \& print $fh $data; .Ve .SH "ABSTRACT" .IX Header "ABSTRACT" Perl bindings for the \s-1SANE \s0(Scanner Access Now Easy) Project. This module allows 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 \s-1API. \s0 .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Sane module allows a Perl developer to use SANE-compatible scanners. Find out more about \s-1SANE\s0 at . .PP Most methods set \f(CW$Sane::STATUS\fR, which is overloaded to give either an integer as dictated by the \s-1SANE\s0 standard, or the the corresponding message, as required. .SS "Sane\->get_version" .IX Subsection "Sane->get_version" Returns an array with the \s-1SANE_VERSION_\s0(MAJOR|MINOR|BUILD) versions: .PP .Vb 1 \& join(\*(Aq.\*(Aq,Sane\->get_version) .Ve .SS "Sane\->get_version_scalar" .IX Subsection "Sane->get_version_scalar" Returns an scalar with the \s-1SANE_VERSION_\s0(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. .SS "Sane\->get_devices" .IX Subsection "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 \fIsane_exit()\fR is performed. This function can be called repeatedly to detect when new devices become available. .PP If argument local_only is true, only local devices are returned (devices directly attached to the machine that \s-1SANE\s0 is running on). If it is false, the device list includes all remote devices that are accessible to the \s-1SANE\s0 library. .PP .Vb 7 \& my @devices = Sane\->get_devices; \& if ($Sane::STATUS == SANE_STATUS_GOOD) { \& print "Name: $devices[0]\->{name}\en"; \& print "Vendor: $devices[0]\->{vendor}\en"; \& print "Model: $devices[0]\->{model}\en"; \& print "Type: $devices[0]\->{type}\en"; \& } .Ve .SS "Sane::Device\->open" .IX Subsection "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 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). .PP .Vb 1 \& my $device = Sane::Device\->open($device_name); .Ve .SS "Sane::Device\->get_option_descriptor" .IX Subsection "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 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 Sane::Device object (the count includes option 0). If n is not a valid option index, the function croaks. .PP .Vb 11 \& my $option = $device\->get_option_descriptor($n); \& if ($Sane::STATUS == SANE_STATUS_GOOD) { \& print "Name: $option\->{name}\en"; \& print "Name: $option\->{title}\en"; \& print "Name: $option\->{desc}\en"; \& print "Name: $option\->{type}\en"; \& print "Name: $option\->{unit}\en"; \& print "Name: $option\->{cap}\en"; \& print "Name: $option\->{max_values}\en"; \& print "Name: $option\->{constraint_type}\en"; \& } .Ve .PP The contents of the name, title, desc, type, unit, cap and constraint_type are as the C \s-1API\s0 description (). There is a further constraint key that either contains an array with the possible option values, or a hash with max, min, and quant keys. .PP The max_values key replaced the size key in the C \s-1API,\s0 and contains the maximum number of values that the option may contain. .SS "Sane::Device\->get_option" .IX Subsection "Sane::Device->get_option" Returns the current value of the selected option. .PP .Vb 4 \& my $value = $device\->get_option($n); \& if ($Sane::STATUS == SANE_STATUS_GOOD) { \& print "value: $value\en"; \& } .Ve .PP For \f(CW$option\fR\->{max_values} > 1, \f(CW$value\fR is a reference to an array. .SS "Sane::Device\->set_auto" .IX Subsection "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. .PP .Vb 1 \& $device\->set_auto($n); .Ve .SS "Sane::Device\->set_option" .IX Subsection "Sane::Device->set_option" Sets the selected option, returning flags in \f(CW$info\fR, which are described in the C \s-1API \s0(). .PP .Vb 6 \& $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\en"; \& } .Ve .PP For \f(CW$option\fR\->{max_values} > 1, \f(CW$value\fR can be a reference to an array. .SS "Sane::Device\->get_parameters" .IX Subsection "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 (Sane::Device\->\fIstart()\fR 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 Sane::Device\->\fIstart()\fR 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. .PP .Vb 9 \& $param = $device\->get_parameters; \& if ($Sane::STATUS == SANE_STATUS_GOOD) { \& print "format $param\->{format}\en"; \& print "last_frame $param\->{last_frame}\en"; \& print "bytes_per_line $param\->{bytes_per_line}\en"; \& print "pixels_per_line $param\->{pixels_per_line}\en"; \& print "lines $param\->{lines}\en"; \& print "depth $param\->{depth}\en"; \& } .Ve .PP Please see the C documentation () for details of the above values. .SS "Sane::Device\->start" .IX Subsection "Sane::Device->start" This function initiates aquisition of an image from the device specified. .PP .Vb 1 \& $device\->start; .Ve .SS "Sane::Device\->read" .IX Subsection "Sane::Device->read" This function is used to read image data from the device specified. The number of bytes returned in \f(CW$buf\fR is stored in \f(CW$len\fR. A backend must set this to zero when a status other than \&\s-1SANE_STATUS_GOOD\s0 is returned. When the call succeeds, the number of bytes returned can be anywhere in the range from 0 to maxlen bytes. .PP .Vb 3 \& $param = $device\->get_parameters; \& $maxlen = $param\->{bytes_per_line}; \& ($buf, $len) = $test\->read ($maxlen); .Ve .PP 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. .IP "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)." 4 .IX Item "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)." .PD 0 .ie n .IP "2. If the device is in non-blocking I/O mode, the call returns immediately with status \s-1SANE_STATUS_GOOD\s0 and with $len set to zero." 4 .el .IP "2. If the device is in non-blocking I/O mode, the call returns immediately with status \s-1SANE_STATUS_GOOD\s0 and with \f(CW$len\fR set to zero." 4 .IX Item "2. If the device is in non-blocking I/O mode, the call returns immediately with status SANE_STATUS_GOOD and with $len set to zero." .PD .PP The I/O mode of the device can be set via a call to Sane::Device\->\fIset_io_mode()\fR. .SS "Sane::Device\->cancel" .IX Subsection "Sane::Device->cancel" This function is used to immediately or as quickly as possible cancel the currently pending operation of the device. .PP .Vb 1 \& $device\->cancel; .Ve .PP This function can be called at any time (as long as \f(CW$device\fR 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 operaton 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 returns (typically with a status value of \s-1SANE_STATUS_CANCELLED\s0). Since the \s-1SANE API\s0 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. .SS "Sane::Device\->set_io_mode" .IX Subsection "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 \f(CW$bool\fR is \&\s-1SANE_TRUE,\s0 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 Sane::Device\->\fIstart()\fR has been performed. .PP .Vb 1 \& $device\->set_io_mode ($bool); .Ve .PP 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 status value \s-1SANE_STATUS_UNSUPPORTED\s0 is returned. Blocking I/O must be supported by all backends, so calling this function with \&\s-1SANE_FALSE\s0 is guaranteed to complete successfully. .SS "Sane::Device\->get_select_fd" .IX Subsection "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 Sane::Device\->\fIread()\fR will return at least one byte of data). .PP .Vb 1 \& $fd = $device\->get_select_fd; .Ve .PP This function can be called only after a call to Sane::Device\->\fIstart()\fR has been performed and the returned file-descriptor is guaranteed to remain valid for the duration of the current image acquisition (i.e., until Sane::Device\->\fIcancel()\fR or Sane::Device\->\fIstart()\fR get called again or until Sane::Device\->\fIread()\fR returns with status \s-1SANE_STATUS_EOF\s0). Indeed, a backend must guarantee to close the returned select file descriptor at the point when the next Sane::Device\->\fIread()\fR call would return \s-1SANE_STATUS_EOF.\s0 This is necessary to ensure the application can detect when this condition occurs without actually having to call Sane::Device\->\fIread()\fR. .PP A backend may elect not to support this operation. In such a case, the function returns with status code \s-1SANE_STATUS_UNSUPPORTED.\s0 .PP 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 \fIselect()\fR or \&\fIpoll()\fR under \s-1UNIX\s0). If any other operation is performed on the file descriptor, the behavior of the backend becomes unpredictable. Once the file-descriptor signals ``readable'' status, it will remain in that state until a call to \fIsane_read()\fR 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. .SS "Sane::Device\->write_pnm_header" .IX Subsection "Sane::Device->write_pnm_header" This function is a pure-Perl helper function to write a \s-1PNM\s0 header. It will fetch the current image settings using Sane::Device\->get_parameters, if they are not already provided, e.g.: .PP .Vb 1 \& $device\->write_pnm_header($fh); .Ve .PP or .PP .Vb 4 \& $parm = $device\->get_parameters; \& $device\->write_pnm_header ($fh, $parm\->{format}, \& $parm\->{pixels_per_line}, \& $parm\->{lines}, $parm\->{depth}); .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" The \s-1SANE\s0 Standard Reference is a handy companion. The Perl bindings follow the C \s-1API\s0 very closely, and the C reference documentation should be considered the canonical source. .SH "AUTHOR" .IX Header "AUTHOR" Jeffrey Ratcliffe, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2008\-\-2012 by Jeffrey Ratcliffe .PP 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.