diff options
Diffstat (limited to 'include/sane/sanei_scsi.h')
| -rw-r--r-- | include/sane/sanei_scsi.h | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/include/sane/sanei_scsi.h b/include/sane/sanei_scsi.h new file mode 100644 index 0000000..21c4561 --- /dev/null +++ b/include/sane/sanei_scsi.h @@ -0,0 +1,332 @@ +/* sane - Scanner Access Now Easy. + Copyright (C) 1996, 1997 David Mosberger-Tang + This file is part of the SANE package. + + SANE is free software; you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + SANE is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public + License for more details. + + You should have received a copy of the GNU General Public License + along with sane; see the file COPYING. If not, write to the Free + Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + As a special exception, the authors of SANE give permission for + additional uses of the libraries contained in this release of SANE. + + The exception is that, if you link a SANE library with other files + to produce an executable, this does not by itself cause the + resulting executable to be covered by the GNU General Public + License. Your use of that executable is in no way restricted on + account of linking the SANE library code into it. + + This exception does not, however, invalidate any other reasons why + the executable file might be covered by the GNU General Public + License. + + If you submit changes to SANE to the maintainers to be included in + a subsequent release, you agree by submitting the changes that + those changes may be distributed with this exception intact. + + If you write modifications of your own for SANE, it is your choice + whether to permit this exception to apply to your modifications. + If you do not wish that, delete this exception notice. +*/ + +/** @file sanei_scsi.h + * Generic interface to SCSI drivers. + * @sa sanei_usb.h, sanei_ab306.h,sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, + * and man sane-scsi(5) for user-oriented documentation + */ + +#ifndef sanei_scsi_h +#define sanei_scsi_h + +#ifdef HAVE_CONFIG_H +#include <config.h> +#endif + +#include <sys/types.h> + +#include <sane/sane.h> + +/** Sense handler + * + * The sense handler can be implemented in backends. It's for deciding + * which sense codes should be considered an error and which shouldn't. + * + * @param fd file descriptor + * @param sense_buffer pointer to buffer containing sense codes + * @param arg pointer to data buffer + * + * @return + * - SANE_STATUS_GOOD - on success (sense isn't regarded as error) + * - any other status if sense code is regarded as error + */ +typedef SANE_Status (*SANEI_SCSI_Sense_Handler) (int fd, + u_char *sense_buffer, + void *arg); +/** Maximum size of a SCSI request + */ +extern int sanei_scsi_max_request_size; + +/** Find SCSI devices. + * + * Find each SCSI device that matches the pattern specified by the + * arguments. String arguments can be "omitted" by passing NULL, + * integer arguments can be "omitted" by passing -1. + * + * Example: vendor="HP" model=NULL, type=NULL, bus=3, id=-1, lun=-1 would + * attach all HP devices on SCSI bus 3. + * + * @param vendor + * @param model + * @param type + * @param bus + * @param channel + * @param id + * @param lun + * @param attach callback invoked once for each device, dev is the real devicename (passed to attach callback) + * + */ +extern void sanei_scsi_find_devices (const char *vendor, const char *model, + const char *type, + int bus, int channel, int id, int lun, + SANE_Status (*attach) (const char *dev)); + + +/** Open a SCSI device + * + * Opens a SCSI device by its device filename and returns a file descriptor. + * If it's necessary to adjust the SCSI buffer size, use + * sanei_scsi_open_extended(). + * + * @param device_name name of the devicefile, e.g. "/dev/sg0" + * @param fd file descriptor + * @param sense_handler called whenever the SCSI driver returns a sense buffer + * @param sense_arg pointer to data for the sense handler + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to + * permissions + * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) + * - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occured + * + * @sa sanei_scsi_open_extended(), HAVE_SANEI_SCSI_OPEN_EXTENDED + */ +extern SANE_Status sanei_scsi_open (const char * device_name, int * fd, + SANEI_SCSI_Sense_Handler sense_handler, + void *sense_arg); + +/** Open a SCSI device and set the buffer size + * + * The extended open call allows a backend to ask for a specific buffer + * size. sanei_scsi_open_extended() tries to allocate a buffer of the size + * given by *buffersize upon entry to this function. If + * sanei_scsi_open_extended returns successfully, *buffersize contains the + * available buffer size. This value may be both smaller or larger than the + * value requested by the backend; it can even be zero. The backend must + * decide, if it got enough buffer memory to work. + * + * Note that the value of *buffersize may differ for different files. + * + * @param device_name name of the devicefile, e.g. "/dev/sg0" + * @param fd file descriptor + * @param sense_handler called whenever the SCSI driver returns a sense buffer + * @param sense_arg pointer to data for the sense handler + * @param buffersize size of the SCAI request buffer (in bytes) + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to + * permissions + * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) + * - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occured + * + * @sa sanei_scsi_open(), HAVE_SANEI_SCSI_OPEN_EXTENDED + */ +extern SANE_Status sanei_scsi_open_extended ( + const char * device_name, int * fd, + SANEI_SCSI_Sense_Handler sense_handler, + void *sense_arg, int *buffersize); + +/** Do we have sanei_scsi_open_extended()? + * + * Let backends decide, which open call to use: if + * HAVE_SANEI_SCSI_OPEN_EXTENDED is defined, sanei_scsi_open_extended may be + * used. May also be used to decide, if sanei_scsi_req_flush_all or + * sanei_scsi_req_flush_all_extended() should be used. + * + * @sa sanei_scsi_open(), sanei_scsi_open_extended() +*/ +#define HAVE_SANEI_SCSI_OPEN_EXTENDED + +/** Enqueue SCSI command + * + * One or more scsi commands can be enqueued by calling sanei_scsi_req_enter(). + * + * NOTE: Some systems may not support multiple outstanding commands. On such + * systems, sanei_scsi_req_enter() may block. In other words, it is not proper + * to assume that enter() is a non-blocking routine. + * + * @param fd file descriptor + * @param src pointer to the SCSI command and associated write data (if any) + * @param src_size length of the command and data + * @param dst pointer to a buffer in which data is returned; NULL if no data is + * returned + * @param dst_size on input, the size of the buffer pointed to by dst, on exit, + * set to the number of bytes returned in the buffer (which is less than or equal + * to the buffer size; may be NULL if no data is expected + * @param idp pointer to a void* that uniquely identifies the entered request + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver + * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) + * - SANE_STATUS_INVAL - if a locking or an unknown error occured + * @sa sanei_scsi_req_enter2() + * +*/ +extern SANE_Status sanei_scsi_req_enter (int fd, + const void * src, size_t src_size, + void * dst, size_t * dst_size, + void **idp); + +/** Enqueue SCSI command and separated data + * + * Same as sanei_scsi_req_enter(), but with separate buffers for the SCSI + * command and for the data to be sent to the device. + * + * With sanei_scsi_req_enter(), the length of te SCSI command block must be + * guessed. While that works in most cases, Canon scanners for example use the + * vendor specific commands 0xd4, 0xd5 and 0xd6. The Canon scanners want to + * get 6 byte command blocks for these commands, but sanei_scsi_req_enter() and + * sanei_scsi_cmd() send 12 bytes. + * + * If dst_size and *dst_size are non-zero, a "read command" (ie, data transfer + * from the device to the host) is assumed. + * + * @param fd file descriptor + * @param cmd pointer to SCSI command + * @param cmd_size size of the command + * @param src pointer to the buffer with data to be sent to the scanner + * @param src_size size of src buffer + * @param dst pointer to a buffer in which data is returned; NULL if no data is + * returned + * @param dst_size on input, the size of the buffer pointed to by dst, on exit, + * set to the number of bytes returned in the buffer (which is less than or equal + * to the buffer size; may be NULL if no data is expected + * @param idp pointer to a void* that uniquely identifies the entered request + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver + * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) + * - SANE_STATUS_INVAL - if a locking or an unknown error occured + * @sa sanei_scsi_req_enter() + */ +extern SANE_Status sanei_scsi_req_enter2 (int fd, + const void * cmd, size_t cmd_size, + const void * src, size_t src_size, + void * dst, size_t * dst_size, + void **idp); + +/** Wait for SCSI command + * + * Wait for the completion of the SCSI command with id ID. + * + * @param id id used in sanei_scsi_req_enter() + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_DEVICE_BUSY - if the device is busy (try again later) + * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver +*/ +extern SANE_Status sanei_scsi_req_wait (void *id); + +/** Send SCSI command + * + * This is a convenience function that is equivalent to a pair of + * sanei_scsi_req_enter()/sanei_scsi_req_wait() calls. + * + * @param fd file descriptor + * @param src pointer to the SCSI command and associated write data (if any) + * @param src_size length of the command and data + * @param dst pointer to a buffer in which data is returned; NULL if no data is + * returned + * @param dst_size on input, the size of the buffer pointed to by dst, on exit, + * set to the number of bytes returned in the buffer (which is less than or equal + * to the buffer size; may be NULL if no data is expected + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver + * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) + * - SANE_STATUS_INVAL - if a locking or an unknown error occured + * + * @sa sanei_scsi_cmd2(), sanei_scsi_req_enter(), sanei_scsi_req_wait() + */ +extern SANE_Status sanei_scsi_cmd (int fd, + const void * src, size_t src_size, + void * dst, size_t * dst_size); + +/** Send SCSI command and separated data + * + * This is a convenience function that is equivalent to a pair of + * sanei_scsi_req_enter2()/sanei_scsi_req_wait() calls. + * + * @param fd file descriptor + * @param cmd pointer to SCSI command + * @param cmd_size size of the command + * @param src pointer to the buffer with data to be sent to the scanner + * @param src_size size of src buffer + * @param dst pointer to a buffer in which data is returned; NULL if no data is + * returned + * @param dst_size on input, the size of the buffer pointed to by dst, on exit, + * set to the number of bytes returned in the buffer (which is less than or equal + * to the buffer size; may be NULL if no data is expected + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver + * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) + * - SANE_STATUS_INVAL - if a locking or an unknown error occured + * + * @sa sanei_scsi_cmd(), sanei_scsi_req_enter(), sanei_scsi_req_wait() + */ +extern SANE_Status sanei_scsi_cmd2 (int fd, + const void * cmd, size_t cmd_size, + const void * src, size_t src_size, + void * dst, size_t * dst_size); + +/** Flush queue + * + * Flush all pending SCSI commands. This function work only, if zero or one + * SCSI file handles are open. + * + * @sa sanei_scsi_req_flush_all_extended() +*/ +extern void sanei_scsi_req_flush_all (void); + +/** Flush queue for handle + * + * Flush all SCSI commands pending for one handle + * + * @param fd file descriptor + * + * @sa sanei_scsi_req_flush_all() + */ +extern void sanei_scsi_req_flush_all_extended (int fd); + +/** Close a SCSI device + * + * @param fd file descriptor + * + */ +extern void sanei_scsi_close (int fd); + +#endif /* sanei_scsi_h */ |