From 1145733c29db0a678537ce99ff60e21613f622a8 Mon Sep 17 00:00:00 2001 From: Igor Pashev Date: Fri, 6 Jan 2023 10:02:49 +0200 Subject: Import iscan 2.30.4-2 --- include/sane/sanei.h | 160 ++++++++++++++ include/sane/sanei_config.h | 175 +++++++++++++++ include/sane/sanei_debug.h | 153 +++++++++++++ include/sane/sanei_magic.h | 154 +++++++++++++ include/sane/sanei_pio.h | 55 +++++ include/sane/sanei_scsi.h | 332 ++++++++++++++++++++++++++++ include/sane/sanei_usb.h | 515 ++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 1544 insertions(+) create mode 100644 include/sane/sanei.h create mode 100644 include/sane/sanei_config.h create mode 100644 include/sane/sanei_debug.h create mode 100644 include/sane/sanei_magic.h create mode 100644 include/sane/sanei_pio.h create mode 100644 include/sane/sanei_scsi.h create mode 100644 include/sane/sanei_usb.h (limited to 'include') diff --git a/include/sane/sanei.h b/include/sane/sanei.h new file mode 100644 index 0000000..ece1beb --- /dev/null +++ b/include/sane/sanei.h @@ -0,0 +1,160 @@ +/* sane - Scanner Access Now Easy. + Copyright (C) 1996 David Mosberger-Tang and Andreas Beck + Copyright (C) 2002, 2003 Henning Meier-Geinitz + + 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.h + * Convenience macros and function declarations for backends + * @sa sanei_backend.h sanei_thread.h + */ + +/* Doxygen documentation */ + +/** @mainpage SANEI (SANE internal routines) documentation + * + * @image html sane-logo2.jpg + * @section intro Introduction + * + * The header files in the include/sane/ directory named sanei_*.h provide + * function declarations and macros that can be used by every SANE backend. + * Their implementations can be found in the sanei/ directory. The code aims + * to be platform-independent to avoid lots of \#ifdef code in the backends. + * Please use the SANEI functions wherever possible. + * + * This documentation was created by the use of doxygen, the + * doc/doxygen-sanei.conf configuration file and documentation in the sanei_*.h + * files. + * + * This documentation is far from complete. Any help is appreciated. + * + * @section additional Additional documentation + * - The SANE standard can be found at the SANE webserver, + * though the PostScript version produced from the source may be more recent. + * - Information on how to write a backend: backend-writing.txt. + * - General SANE documentation is on the SANE documentation + * page. + * + * @section contact Contact + * + * The common way to contact the developers of SANE is the sane-devel + * mailing list. See the mailing list webpage + * for details. That's the place to ask questions, report bugs, or announce + * a new backend. + * + */ + +#ifndef sanei_h +#define sanei_h + +#include + +/** @name Public macros and functions + * @{ + */ +/** @def STRINGIFY(x) + * Turn parameter into string. + */ +/** @def PASTE(x,y) + * Concatenate parameters. + * + */ +/** @def NELEMS(a) + * Return number of elements of an array. + * + */ + +/** @fn extern SANE_Status sanei_check_value (const SANE_Option_Descriptor * opt, void * value); + * Check the constraints of a SANE option. + * + * @param opt option to check + * @param value value of the option + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_INVAL - if the value doesn't fit inside the constraint + * or any other error occured + * @sa sanei_constrain_value() + */ + +/** @fn extern SANE_Status sanei_constrain_value (const SANE_Option_Descriptor * opt, void * value, SANE_Word * info); + * Check the constraints of a SANE option and adjust its value if necessary. + * + * Depending on the type of the option and constraint, value is modified + * to fit inside constraint. + * + * @param opt option to check + * @param value value of the option + * @param info info is set to SANE_INFO_INEXACT if value was changed + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_INVAL - if the function wasn't able to fit value into the + * constraint or any other error occured + * @sa sanei_check_value() + */ + +/* @} */ + +/* A few convenience macros: */ +/** @hideinitializer */ +#define NELEMS(a) ((int)(sizeof (a) / sizeof (a[0]))) + +/** @hideinitializer */ +#define STRINGIFY1(x) #x +/** @hideinitializer */ +#define STRINGIFY(x) STRINGIFY1(x) + +/** @hideinitializer */ +#define PASTE1(x,y) x##y +/** @hideinitializer */ +#define PASTE(x,y) PASTE1(x,y) + +extern SANE_Status sanei_check_value (const SANE_Option_Descriptor * opt, + void * value); + +extern SANE_Status sanei_constrain_value (const SANE_Option_Descriptor * opt, + void * value, SANE_Word * info); + + +#endif /* sanei_h */ diff --git a/include/sane/sanei_config.h b/include/sane/sanei_config.h new file mode 100644 index 0000000..cf877cf --- /dev/null +++ b/include/sane/sanei_config.h @@ -0,0 +1,175 @@ +/* sane - Scanner Access Now Easy. + Copyright (C) 1997 Jeffrey S. Freedman + This file is part of the SANE package. + + This program 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. + + This program 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 this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, + MA 02111-1307, 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_config.h + * Generic configuration support. + * + * Use the functions of this header file if you want to read and analyze + * configuration files. +*/ + +#ifndef sanei_config_h +#define sanei_config_h 1 + +#include +#include + +/** Search configuration file \a name along directory list and return file + * pointer if such a file exists. + * + * The following directory list is used: + * 1st: SANE_CONFIG_DIR environment variable. + * 2nd: PATH_SANE_CONFIG_DIR set during configuration. + * 3rd: Current directory. + * @param name filename with extension but without path (such as "mustek.conf") + * + * @return file pointer, or NULL if not found + * + */ +extern FILE *sanei_config_open (const char *name); + +/** Read a line from configuration file. + * + * Strips all unwanted chars. Use this instead of fgets() to remove + * line ending chars on all known platforms. + * + * @param str points to the buffer for the line + * @param n size of the buffer + * @param stream file pointer + * + * @return \a str on success and NULL on error +*/ +extern char *sanei_config_read (char *str, int n, FILE *stream); + +/** Remove all whitespace from the beginning of a string. + * + * @param str string + * + * @return string without leading whitespace + * + */ +extern const char *sanei_config_skip_whitespace (const char *str); + + +/** Scan a string constant from a line of text and return a malloced copy + * of it. + * + * It's the responsibility of the caller to free the returned string constant + * at an appropriate time. Whitespace in front of the string constant is + * ignored. Whitespace can be included in the string constant by enclosing it + * in double-quotes. + * + * @param str line of text to scan for a string constant + * @param string_const copy of the string constant + * + * @return a pointer to the position in str where the scan stopped + */ +extern const char *sanei_config_get_string (const char *str, + char **string_const); + +/** Expand device name patterns into a list of devices. + * + * Apart from a normal device name (such as /dev/sdb), this function currently + * supports SCSI device specifications of the form: + * + * scsi VENDOR MODEL TYPE BUS CHANNEL ID LUN + * + * Where VENDOR is the desired vendor name. MODEL is the desired model name. + * TYPE is the desired device type. All of these can be set to * to match + * anything. To include whitespace in these strings, enclose them in + * double-quotes ("). BUS, ID, and LUN are the desired SCSI bus, id, and + * logical-unit numbers. These can be set to * or simply omitted to match + * anything. + * + * @param name device name pattern + * @param attach attach function + */ +extern void sanei_config_attach_matching_devices (const char *name, + SANE_Status (*attach) + (const char *dev)); + +/** this structure holds the description of configuration options. There is + * a list for options and another for their values. + * These lists are used when the configuration file is + * parsed. Read values are stored in Option_Value. Helpers functions are + * provided to access values easily */ +typedef struct +{ + /** number of options */ + SANE_Int count; + + /** NULL terminated list of configuration option */ + SANE_Option_Descriptor **descriptors; + + /** values for the configuration options */ + void **values; + +} SANEI_Config; + +/** Parse configuration file, reading configuration options and trying to + * attach devices found in file. + * + * The option are gathered in a single configuration structure. Each time + * a line holds a value that is not an option, the attach function is called + * with the name found and the configuration structure with it's current values. + * + * @param config_file name of the configuration file to read + * @param config configuration structure to be filled during configuration + * parsing and passed to the attach callback function + * @param config_attach attach with config callback function + * + * @return SANE_STATUS_GOOD if no errors + * SANE_STATUS_ACCESS_DENIED if configuration file can't be opened + */ +extern SANE_Status sanei_configure_attach ( + const char *config_file, + SANEI_Config *config, + SANE_Status (*config_attach)(SANEI_Config *config, const char *devname) +); + +/** Return the list of config directories, extracted from the SANE_CONFIG_DIR + * environment variable and the default paths. + * @return a string containing the configuration paths, separated by the + * operating system's path separator + */ +extern const char *sanei_config_get_paths (void); + +#endif /* sanei_config_h */ diff --git a/include/sane/sanei_debug.h b/include/sane/sanei_debug.h new file mode 100644 index 0000000..557f8a7 --- /dev/null +++ b/include/sane/sanei_debug.h @@ -0,0 +1,153 @@ +/** @file sanei_debug.h + * Support for printing debug messages. + * + * Use the functions of this header file to print debug or warning messages. + */ + +#ifndef _SANEI_DEBUG_H +#define _SANEI_DEBUG_H + +#include + +/** @name Public macros + * These macros can be used in backends and other SANE-related + * code. + * + * Before including sanei_debug.h, the following macros must be set: + * + * - BACKEND_NAME - The name of your backend without double-quotes (must be set in any case) + * - STUBS - If this is defined, no macros will be included. Used in + * backends consisting of more than one .c file. + * - DEBUG_DECLARE_ONLY - Generates prototypes instead of functions. Used in + * backends consisting of more than one .c file. + * - DEBUG_NOT_STATIC - Doesn't generate static functions. Used in header files if + * they are include in more than one .c file. + * + * @{ + */ + +/** @def DBG_INIT() + * Initialize sanei_debug. + * + * Call this function before you use any DBG function. + */ + +/** @def DBG(level, fmt, ...) + * Print a message at debug level `level' or higher using a printf-like + * function. Example: DBG(1, "sane_open: opening fd \%d\\n", fd). + * + * @param level debug level + * @param fmt format (see man 3 printf for details) + * @param ... additional arguments + */ + +/** @def IF_DBG(x) + * Compile code only if debugging is enabled. + * + * Expands to x if debug support is enabled at compile-time. If NDEBUG is + * defined at compile-time this macro expands to nothing. + * + * @param x code to expand when debugging is enabled + */ + +/** + * @def DBG_LEVEL + * Current debug level. + * + * You can only read this "variable". + */ + +/** @def ENTRY(name) + * Expands to sane_BACKEND_NAME_name. + * + * Example: ENTRY(init) in mustek.c will expand to sane_mustek_init. + */ + +/* @} */ + + + /** @hideinitializer*/ +#define ENTRY(name) PASTE(PASTE(PASTE(sane_,BACKEND_NAME),_),name) + +#ifdef NDEBUG + +extern void sanei_debug_ndebug (int level, const char *msg, ...); + +# define DBG_LEVEL (0) +# define DBG_INIT() +# define DBG sanei_debug_ndebug +# define IF_DBG(x) + +#else /* !NDEBUG */ + + /** @hideinitializer*/ +# define DBG_LEVEL PASTE(sanei_debug_,BACKEND_NAME) + +# if defined(BACKEND_NAME) && !defined(STUBS) +# ifdef DEBUG_DECLARE_ONLY +extern int DBG_LEVEL; +# else /* !DEBUG_DECLARE_ONLY */ +int DBG_LEVEL = 0; +# endif /* DEBUG_DECLARE_ONLY */ +# endif /* BACKEND_NAME && !STUBS */ + + /** @hideinitializer*/ +# define DBG_INIT() \ + sanei_init_debug (STRINGIFY(BACKEND_NAME), &DBG_LEVEL) + + /** @hideinitializer*/ +# define DBG_LOCAL PASTE(DBG_LEVEL,_call) + + +# ifndef STUBS + +# ifdef DEBUG_DECLARE_ONLY + +extern void DBG_LOCAL (int level, const char *msg, ...) +#ifdef __GNUC__ +__attribute__ ((format (printf, 2, 3))) +#endif +; + +# else /* !DEBUG_DECLARE_ONLY */ + +# include + +extern void sanei_debug_msg + (int level, int max_level, const char *be, const char *fmt, va_list ap); + +#ifdef __GNUC__ +# ifndef DEBUG_NOT_STATIC +static +# endif /* !DEBUG_NOT_STATIC */ +void DBG_LOCAL (int level, const char *msg, ...) __attribute__ ((format (printf, 2, 3))); +#endif /* __GNUC__ */ + +# ifndef DEBUG_NOT_STATIC +static +# endif /* !DEBUG_NOT_STATIC */ +void +DBG_LOCAL (int level, const char *msg, ...) +{ + va_list ap; + + va_start (ap, msg); + sanei_debug_msg (level, DBG_LEVEL, STRINGIFY(BACKEND_NAME), msg, ap); + va_end (ap); +} + +# endif /* DEBUG_DECLARE_ONLY */ + +# endif /* !STUBS */ + + /** @hideinitializer*/ +# define DBG DBG_LOCAL + +extern void sanei_init_debug (const char * backend, int * debug_level_var); + + /** @hideinitializer*/ +# define IF_DBG(x) x + +#endif /* NDEBUG */ + +#endif /* _SANEI_DEBUG_H */ diff --git a/include/sane/sanei_magic.h b/include/sane/sanei_magic.h new file mode 100644 index 0000000..9e87e00 --- /dev/null +++ b/include/sane/sanei_magic.h @@ -0,0 +1,154 @@ +/* sane - Scanner Access Now Easy. + + Copyright (C) 2009 m. allan noah + + 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_magic.h + * This file provides an interface to simple image post-processing functions + * + * Currently, three operations are provided: + * - Deskew (correct rotated scans, by detecting media edges) + * - Autocrop (reduce image size to minimum rectangle containing media) + * - Despeckle (replace dots of significantly different color with background) + * + * Note that these functions are simplistic, and are expected to change. + * Patches and suggestions are welcome. + */ + +#ifndef SANEI_MAGIC_H +#define SANEI_MAGIC_H + +/** Initialize sanei_magic. + * + * Call this before any other sanei_magic function. + */ +extern void sanei_magic_init( void ); + +/** Update the image buffer, replacing dots with surrounding background color + * + * @param params describes image + * @param buffer contains image data + * @param diam maximum dot diameter to remove + * + * @return + * - SANE_STATUS_GOOD - success + * - SANE_STATUS_INVAL - invalid image parameters + */ +extern SANE_Status +sanei_magic_despeck (SANE_Parameters * params, SANE_Byte * buffer, + SANE_Int diam); + +/** Find the skew of the media inside the image, via edge detection. + * + * @param params describes image + * @param buffer contains image data + * @param dpiX horizontal resolution + * @param dpiY vertical resolution + * @param[out] centerX horizontal coordinate of center of rotation + * @param[out] centerY vertical coordinate of center of rotation + * @param[out] finSlope slope of rotation + * + * @return + * - SANE_STATUS_GOOD - success + * - SANE_STATUS_NO_MEM - not enough memory + * - SANE_STATUS_INVAL - invalid image parameters + * - SANE_STATUS_UNSUPPORTED - slope angle too shallow to detect + */ +extern SANE_Status +sanei_magic_findSkew(const SANE_Parameters * params, const SANE_Byte * buffer, + int dpiX, int dpiY, int * centerX, int * centerY, double * finSlope); + +/** Correct the skew of the media inside the image, via simple rotation + * + * @param params describes image + * @param buffer contains image data + * @param centerX horizontal coordinate of center of rotation + * @param centerY vertical coordinate of center of rotation + * @param slope slope of rotation + * @param bg_color the replacement color for edges exposed by rotation + * + * @return + * - SANE_STATUS_GOOD - success + * - SANE_STATUS_NO_MEM - not enough memory + * - SANE_STATUS_INVAL - invalid image parameters + */ +extern SANE_Status +sanei_magic_rotate (SANE_Parameters * params, SANE_Byte * buffer, + int centerX, int centerY, double slope, int bg_color); + +/** Find the edges of the media inside the image, parallel to image edges + * + * @param params describes image + * @param buffer contains image data + * @param dpiX horizontal resolution + * @param dpiY vertical resolution + * @param[out] top vertical offset to upper edge of media + * @param[out] bot vertical offset to lower edge of media + * @param[out] left horizontal offset to left edge of media + * @param[out] right horizontal offset to right edge of media + * + * @return + * - SANE_STATUS_GOOD - success + * - SANE_STATUS_NO_MEM - not enough memory + * - SANE_STATUS_UNSUPPORTED - edges could not be detected + */ +extern SANE_Status +sanei_magic_findEdges(const SANE_Parameters * params, const SANE_Byte * buffer, + int dpiX, int dpiY, int * top, int * bot, int * left, int * right); + +/** Crop the image, parallel to image edges + * + * @param params describes image + * @param buffer contains image data + * @param top vertical offset to upper edge of crop + * @param bot vertical offset to lower edge of crop + * @param left horizontal offset to left edge of crop + * @param right horizontal offset to right edge of crop + * + * @return + * - SANE_STATUS_GOOD - success + * - SANE_STATUS_NO_MEM - not enough memory + * - SANE_STATUS_INVAL - invalid image parameters + */ +extern SANE_Status +sanei_magic_crop(SANE_Parameters * params, SANE_Byte * buffer, + int top, int bot, int left, int right); + +#endif /* SANEI_MAGIC_H */ diff --git a/include/sane/sanei_pio.h b/include/sane/sanei_pio.h new file mode 100644 index 0000000..61ac414 --- /dev/null +++ b/include/sane/sanei_pio.h @@ -0,0 +1,55 @@ +/* sane - Scanner Access Now Easy. + Copyright (C) 1998 Christian Bucher + Copyright (C) 1998 Kling & Hautzinger GmbH + This file is part of the SANE package. + + This program 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. + + This program 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 this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, + MA 02111-1307, 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. */ + +#ifndef sanei_pio_h +#define sanei_pio_h + +#include + +#include + +extern SANE_Status sanei_pio_open (const char * dev, int * fd); +extern void sanei_pio_close (int fd); +extern int sanei_pio_read (int fd, u_char * buf, int n); +extern int sanei_pio_write (int fd, const u_char * buf, int n); + +#endif /* sanei_pio_h */ + 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 +#endif + +#include + +#include + +/** 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 */ diff --git a/include/sane/sanei_usb.h b/include/sane/sanei_usb.h new file mode 100644 index 0000000..c84e4b0 --- /dev/null +++ b/include/sane/sanei_usb.h @@ -0,0 +1,515 @@ +/* sane - Scanner Access Now Easy. + Copyright (C) 2001, 2002 Henning Meier-Geinitz + Copyright (C) 2003, 2005 Rene Rebe (sanei_read_int,sanei_set_timeout) + Copyright (C) 2008 m. allan noah (sanei_usb_clear_halt) + Copyright (C) 2011 Reinhold Kainhofer (sanei_usb_set_endpoint) + 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_usb.h + * This file provides a generic USB interface. + * + * Currently, two access methods to USB devices are provided: + * - Access to device + * files as used by the Linux kernel USB scanner driver is supported. FreeBSD + * and OpenBSD with their uscanner drivers also work this way. However, + * detection and control messages aren't supported on these platforms. + * - Access using libusb (where available). + * + * A general remark: Do not mix sanei_usb functions with "normal" file-related + * libc functions like open() or close. The device numbers used in sanei_usb + * are not file descriptors. + * + * @sa sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, sanei_scsi.h, and man sane-usb(5) + * for user-oriented documentation + */ + +#ifndef sanei_usb_h +#define sanei_usb_h + +#ifdef HAVE_CONFIG_H +#include +#endif + +#include + +#include /* for size_t */ + +/* USB spec defines */ +#ifndef USB_CLASS_PER_INTERFACE +/* Also defined in libusb */ +/** @name Device and/or interface class codes */ +/* @{ */ +#define USB_CLASS_PER_INTERFACE 0x00 +#define USB_CLASS_AUDIO 0x01 +#define USB_CLASS_COMM 0x02 +#define USB_CLASS_HID 0x03 +#define USB_CLASS_PRINTER 0x07 +#define USB_CLASS_MASS_STORAGE 0x08 +#define USB_CLASS_HUB 0x09 +#define USB_CLASS_DATA 0x0a +#define USB_CLASS_VENDOR_SPEC 0xff +/* @} */ + +/** @name USB descriptor types */ +/* @{ */ +#define USB_DT_DEVICE 0x01 +#define USB_DT_CONFIG 0x02 +#define USB_DT_STRING 0x03 +#define USB_DT_INTERFACE 0x04 +#define USB_DT_ENDPOINT 0x05 +#define USB_DT_HID 0x21 +#define USB_DT_REPORT 0x22 +#define USB_DT_PHYSICAL 0x23 +#define USB_DT_HUB 0x29 +/* @} */ + +/** @name Descriptor sizes per descriptor type */ +/* @{ */ +#define USB_DT_DEVICE_SIZE 18 +#define USB_DT_CONFIG_SIZE 9 +#define USB_DT_INTERFACE_SIZE 9 +#define USB_DT_ENDPOINT_SIZE 7 +#define USB_DT_ENDPOINT_AUDIO_SIZE 9 +#define USB_DT_HUB_NONVAR_SIZE 7 +/* @} */ + +/** @name Endpoint descriptors */ +/* @{ */ +#define USB_ENDPOINT_ADDRESS_MASK 0x0f +#define USB_ENDPOINT_DIR_MASK 0x80 +#define USB_ENDPOINT_TYPE_MASK 0x03 +#define USB_ENDPOINT_TYPE_CONTROL 0 +#define USB_ENDPOINT_TYPE_ISOCHRONOUS 1 +#define USB_ENDPOINT_TYPE_BULK 2 +#define USB_ENDPOINT_TYPE_INTERRUPT 3 +/* @} */ + +/** @name Standard requests */ +/* @{ */ +#define USB_REQ_GET_STATUS 0x00 +#define USB_REQ_CLEAR_FEATURE 0x01 +#define USB_REQ_SET_FEATURE 0x03 +#define USB_REQ_SET_ADDRESS 0x05 +#define USB_REQ_GET_DESCRIPTOR 0x06 +#define USB_REQ_SET_DESCRIPTOR 0x07 +#define USB_REQ_GET_CONFIGURATION 0x08 +#define USB_REQ_SET_CONFIGURATION 0x09 +#define USB_REQ_GET_INTERFACE 0x0A +#define USB_REQ_SET_INTERFACE 0x0B +#define USB_REQ_SYNCH_FRAME 0x0C +/* @} */ + +/** @name USB types */ +/* @{ */ +#define USB_TYPE_STANDARD (0x00 << 5) +#define USB_TYPE_CLASS (0x01 << 5) +#define USB_TYPE_VENDOR (0x02 << 5) +#define USB_TYPE_RESERVED (0x03 << 5) +/* @} */ + +/** @name USB recipients */ +/* @{ */ +#define USB_RECIP_DEVICE 0x00 +#define USB_RECIP_INTERFACE 0x01 +#define USB_RECIP_ENDPOINT 0x02 +#define USB_RECIP_OTHER 0x03 +/* @} */ + +#endif /* not USB_CLASS_PER_INTERFACE */ + +/* Not defined in libsub */ +/** @name USB Masks */ +/* @{ */ +#define USB_TYPE_MASK (0x03 << 5) +#define USB_RECIP_MASK 0x1f +/* @} */ + +/** @name USB directions */ +/* @{ */ +#define USB_DIR_OUT 0x00 +#define USB_DIR_IN 0x80 +/* @} */ + +/** */ +struct sanei_usb_dev_descriptor +{ + SANE_Byte desc_type; + unsigned int bcd_usb; + unsigned int bcd_dev; + SANE_Byte dev_class; + SANE_Byte dev_sub_class; + SANE_Byte dev_protocol; + SANE_Byte max_packet_size; +}; + +/** Initialize sanei_usb. + * + * Call this before any other sanei_usb function. + */ +extern void sanei_usb_init (void); + +/** Get the vendor and product ids by device name. + * + * @param devname + * @param vendor vendor id + * @param product product id + * + * @return + * - SANE_STATUS_GOOD - if the ids could be determined + * - SANE_STATUS_INVAL - if the device is not found + * - SANE_STATUS_UNSUPPORTED - if this method is not supported with the current + * access method + */ +SANE_Status +sanei_usb_get_vendor_product_byname (SANE_String_Const devname, + SANE_Word * vendor, SANE_Word * product); + +/** Get the vendor and product ids. + * + * Currently, only libusb devices and scanners supported by the Linux USB + * scanner module can be found. For the latter method, the Linux version + * must be 2.4.8 or higher. + * + * @param dn device number of an already sanei_usb_opened device + * @param vendor vendor id + * @param product product id + * + * @return + * - SANE_STATUS_GOOD - if the ids could be determined + * - SANE_STATUS_UNSUPPORTED - if the OS doesn't support detection of ids + */ +extern SANE_Status +sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word * vendor, + SANE_Word * product); + +/** Find devices that match given vendor and product ids. + * + * For limitations, see function sanei_usb_get_vendor_product(). + * The function attach is called for every device which has been found. + * + * @param vendor vendor id + * @param product product id + * @param attach attach function + * + * @return SANE_STATUS_GOOD - on success (even if no scanner was found) + */ +extern SANE_Status +sanei_usb_find_devices (SANE_Int vendor, SANE_Int product, + SANE_Status (*attach) (SANE_String_Const devname)); + +/** Open a USB device. + * + * The device is opened by its name devname and the device number is + * returned in dn on success. + * + * Device names can be either device file names for direct access over + * kernel drivers (like /dev/usb/scanner) or libusb names. The libusb format + * looks like this: "libusb:bus-id:device-id". Bus-id and device-id are + * platform-dependent. An example could look like this: "libusb:001:002" + * (Linux). + * + * @param devname name of the device to open + * @param dn device number + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to + * permissions + * - SANE_STATUS_INVAL - on every other error + */ +extern SANE_Status sanei_usb_open (SANE_String_Const devname, SANE_Int * dn); + +/** Set the endpoint for the USB communication + * + * Allows to switch to a different endpoint for the USB communication than + * the default (auto-detected) endpoint. This function can only be called + * after sanei_usb_open. + * + * @param dn device number + * @param ep_type type of endpoint to set (bitwise or of USB_DIR_IN/OUT and + * USB_ENDPOINT_TYPE_BULK/CONTROL/INTERRUPT/ISOCHRONOUS + * @param ep endpoint to use for the given type + * + */ +extern void sanei_usb_set_endpoint (SANE_Int dn, SANE_Int ep_type, SANE_Int ep); + +/** Retrieve the endpoint used for the USB communication + * + * Returns the endpoint used for the USB communication of the given type. + * This function can only be called after sanei_usb_open. + * + * @param dn device number + * @param ep_type type of endpoint to retrieve (bitwise or of USB_DIR_IN/OUT + * and USB_ENDPOINT_TYPE_BULK/CONTROL/INTERRUPT/ISOCHRONOUS + * @return endpoint used for the given type + * + */ +extern SANE_Int sanei_usb_get_endpoint (SANE_Int dn, SANE_Int ep_type); + +/** Close a USB device. + * + * @param dn device number + */ +extern void sanei_usb_close (SANE_Int dn); + +/** Set the libusb timeout for bulk and interrupt reads. + * + * @param timeout the new timeout in ms + */ +extern void sanei_usb_set_timeout (SANE_Int timeout); + +/** Check if sanei_usb_set_timeout() is available. + */ +#define HAVE_SANEI_USB_SET_TIMEOUT + +/** Clear halt condition on bulk endpoints + * + * @param dn device number + */ +extern SANE_Status sanei_usb_clear_halt (SANE_Int dn); + +/** Check if sanei_usb_clear_halt() is available. + */ +#define HAVE_SANEI_USB_CLEAR_HALT + +/** Reset device + * + * @param dn device number + */ +extern SANE_Status sanei_usb_reset (SANE_Int dn); + +/** Initiate a bulk transfer read. + * + * Read up to size bytes from the device to buffer. After the read, size + * contains the number of bytes actually read. + * + * @param dn device number + * @param buffer buffer to store read data in + * @param size size of the data + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_EOF - if zero bytes have been read + * - SANE_STATUS_IO_ERROR - if an error occured during the read + * - SANE_STATUS_INVAL - on every other error + * + */ +extern SANE_Status +sanei_usb_read_bulk (SANE_Int dn, SANE_Byte * buffer, size_t * size); + +/** Initiate a bulk transfer write. + * + * Write up to size bytes from buffer to the device. After the write size + * contains the number of bytes actually written. + * + * @param dn device number + * @param buffer buffer to write to device + * @param size size of the data + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_IO_ERROR - if an error occured during the write + * - SANE_STATUS_INVAL - on every other error + */ +extern SANE_Status +sanei_usb_write_bulk (SANE_Int dn, const SANE_Byte * buffer, size_t * size); + +/** Send/receive a control message to/from a USB device. + * + * This function is only supported for libusb devices and kernel acces with + * Linux 2.4.13 and newer. + * For a detailed explanation of the parameters, have a look at the USB + * specification at the + * www.usb.org developers information page. + * + * @param dn device number + * @param rtype specifies the characteristics of the request (e.g. data + * direction) + * @param req actual request + * @param value parameter specific to the request + * @param index parameter specific to the request (often used to select + * endpoint) + * @param len length of data to send/receive + * @param data buffer to send/receive data + * + * @return + * - SANE_STATUS_GOOD - on success + * - SANE_STATUS_IO_ERROR - on error + * - SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or + * SANE. + */ +extern SANE_Status +sanei_usb_control_msg (SANE_Int dn, SANE_Int rtype, SANE_Int req, + SANE_Int value, SANE_Int index, size_t * size, + SANE_Byte * data); + +/** Initiate a interrupt transfer read. + * + * Read up to size bytes from the interrupt endpoint from the device to + * buffer. After the read, size contains the number of bytes actually read. + * + * @param dn device number + * @param buffer buffer to store read data in + * @param size size of the data + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_EOF - if zero bytes have been read + * - SANE_STATUS_IO_ERROR - if an error occured during the read + * - SANE_STATUS_INVAL - on every other error + * + */ + +extern SANE_Status +sanei_usb_read_int (SANE_Int dn, SANE_Byte * buffer, size_t * size); + +/** Expand device name patterns into a list of devices. + * + * Apart from a normal device name (such as /dev/usb/scanner0 or + * libusb:002:003), this function currently supports USB device + * specifications of the form: + * + * usb VENDOR PRODUCT + * + * VENDOR and PRODUCT are non-negative integer numbers in decimal or + * hexadecimal format. A similar function for SCSI devices can be found + * in include/sane/config.h. + * + * @param name device name pattern + * @param attach attach function + * + */ +extern void +sanei_usb_attach_matching_devices (const char *name, + SANE_Status (*attach) (const char *dev)); + +/** Initiate set configuration. + * + * Change set configuration + * + * @param dn device number + * @param configuration, configuration nummber + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_EOF - if zero bytes have been read + * - SANE_STATUS_IO_ERROR - if an error occured during the read + * - SANE_STATUS_INVAL - on every other error + * + */ + +extern SANE_Status +sanei_usb_set_configuration (SANE_Int dn, SANE_Int configuration); + +/** Initiate claim interface. + * + * Change claim interface + * + * @param dn device number + * @param interface_number interface number + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_EOF - if zero bytes have been read + * - SANE_STATUS_IO_ERROR - if an error occured during the read + * - SANE_STATUS_INVAL - on every other error + * + */ + +extern SANE_Status +sanei_usb_claim_interface (SANE_Int dn, SANE_Int interface_number); + +/** Initiate release interface. + * + * Change release interface + * + * @param dn device number + * @param interface_number interface number + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_EOF - if zero bytes have been read + * - SANE_STATUS_IO_ERROR - if an error occured during the read + * - SANE_STATUS_INVAL - on every other error + * + */ + +extern SANE_Status +sanei_usb_release_interface (SANE_Int dn, SANE_Int interface_number); + +/** Initiate a set altinterface. + * + * Change set alternate + * + * @param dn device number + * @param alternate, alternate nummber + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_EOF - if zero bytes have been read + * - SANE_STATUS_IO_ERROR - if an error occured during the read + * - SANE_STATUS_INVAL - on every other error + * + */ + +extern SANE_Status +sanei_usb_set_altinterface (SANE_Int dn, SANE_Int alternate); + +/** Get some information from the device descriptor + * + * Sometimes it's useful to know something about revisions and + * other stuff reported by the USB system + * + * @param dn device number + * @param desc where to put the information to + * + * @return + * - SANE_STATUS_GOOD - on succes + * - SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or + * SANE. + * - SANE_STATUS_INVAL - on every other error + * + */ + +extern SANE_Status +sanei_usb_get_descriptor( SANE_Int dn, struct sanei_usb_dev_descriptor *desc ); + +/*------------------------------------------------------*/ +#endif /* sanei_usb_h */ -- cgit v1.2.3