diff options
Diffstat (limited to 'backend/pixma_io.h')
| -rw-r--r-- | backend/pixma_io.h | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/backend/pixma_io.h b/backend/pixma_io.h new file mode 100644 index 0000000..004e008 --- /dev/null +++ b/backend/pixma_io.h @@ -0,0 +1,186 @@ +/* SANE - Scanner Access Now Easy. + + Copyright (C) 2006-2007 Wittawat Yamwong <wittawat@web.de> + + 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 PIXMA_IO_H +#define PIXMA_IO_H + +/* TODO: move to pixma_common.h, to reduce the number of files */ + +/*! + * \defgroup IO IO interface + * \brief The IO interface. + * + * Return value of functions that return \c int if not otherwise specified: + * - >= if succeeded + * - < 0 if failed (e.g. \c PIXMA_ETIMEDOUT) + * . + * @{ + */ + +/** Timeout for pixma_read() in milliseconds */ +#define PIXMA_BULKIN_TIMEOUT 20000 +/** Timeout for pixma_write() in milliseconds */ +#define PIXMA_BULKOUT_TIMEOUT 20000 + + +struct pixma_io_t; +struct pixma_config_t; + +/** IO handle */ +typedef struct pixma_io_t pixma_io_t; + + +/** Initialize IO module. It must be called before any other functions in this + * module. + * \return 0 on success or + * - \c PIXMA_ENOMEM + * - \c PIXMA_EACCES + * - \c PIXMA_EIO */ +int pixma_io_init (void); + +/** Shutdown all connections and free resources allocated in this module. */ +void pixma_io_cleanup (void); + +/** Find devices currently connected to the computer. + * \c devnr passed to functions + * - pixma_get_device_config() + * - pixma_get_device_id() + * - pixma_connect() + * . + * should be less than the number of devices returned by this function. + * \param[in] pixma_devices A \c NULL terminated array of pointers to + * array of pixma_config_t which is terminated by setting + * pixma_config_t::name to \c NULL. + * \return Number of devices found */ +unsigned pixma_collect_devices (const char ** conf_devices, + const struct pixma_config_t *const + pixma_devices[]); + +/** Get device configuration. */ +const struct pixma_config_t *pixma_get_device_config (unsigned devnr); + +/** Get a unique ID of the device \a devnr. */ +const char *pixma_get_device_id (unsigned devnr); + +/** Connect to the device and claim the scanner interface. + * \param[in] devnr + * \param[out] handle + * \return 0 on success or + * - \c PIXMA_ENODEV the device is gone from the system. + * - \c PIXMA_EINVAL \a devnr is invalid. + * - \c PIXMA_EBUSY + * - \c PIXMA_EACCES + * - \c PIXMA_ENOMEM + * - \c PIXMA_EIO */ +int pixma_connect (unsigned devnr, pixma_io_t ** handle); + +/** Release the scanner interface and disconnect from the device. */ +void pixma_disconnect (pixma_io_t *); + +/** Activate connection to scanner */ +int pixma_activate (pixma_io_t *); + +/** De-activate connection to scanner */ +int pixma_deactivate (pixma_io_t *); + +/** Reset the USB interface. \warning Use with care! */ +int pixma_reset_device (pixma_io_t *); + +/** Write data to the device. This function may not be interrupted by signals. + * It will return iff + * - \a len bytes have been successfully written or + * - an error (inclusive timeout) occured. + * . + * \note Calling pixma_write(io, buf, n1) and pixma(io, buf+n1, n2) may + * not be the same as pixma_write(io, buf, n1+n2) if n1 is not + * multiple of the maximum packet size of the endpoint. + * \param[in] cmd Data + * \param[in] len Length of data + * \return Number of bytes successfully written (always = \a len) or + * - \c PIXMA_ETIMEDOUT + * - \c PIXMA_EIO + * - \c PIXMA_ENOMEM + * \see #PIXMA_BULKOUT_TIMEOUT */ +int pixma_write (pixma_io_t *, const void *cmd, unsigned len); + +/** Read data from the device. This function may not be interrupted by signals. + * It will return iff + * - \a size bytes have been successfully read, + * - a short packet has been read or + * - an error (inclusive timeout) occured. + * . + * \param[out] buf + * \param[in] size of the buffer + * \return Number of bytes successfully read. A return value of zero means that + * a zero length USB packet was received. Or + * - \c PIXMA_ETIMEDOUT + * - \c PIXMA_EIO + * - \c PIXMA_ENOMEM + * \see #PIXMA_BULKIN_TIMEOUT */ +int pixma_read (pixma_io_t *, void *buf, unsigned size); + +/** Wait for an interrupt. This function can be interrupted by signals. + * \a size should be less than or equal to the maximum packet size. + * \param[out] buf + * \param[in] size of the buffer + * \param[in] timeout in milliseconds; if < 0, wait forever. + * \return Number of bytes successfully read or + * - \c PIXMA_ETIMEDOUT + * - \c PIXMA_EIO + * - \c PIXMA_ENOMEM + * - \c PIXMA_ECANCELED if it was interrupted by a signal. */ +int pixma_wait_interrupt (pixma_io_t *, void *buf, unsigned size, + int timeout); + +/** Enable or disable background interrupt monitoring. + * Background mode is enabled by default. + * \param[in] background if not zero, a URB is submitted in background + * for interrupt endpoint. + * \return 0 on success or + * - \c PIXMA_ENOTSUP + * - \c PIXMA_EIO + * - \c PIXMA_ENOMEM */ +int pixma_set_interrupt_mode (pixma_io_t *, int background); + +/** @} end of IO group */ + +#endif |