1 /* SANE - Scanner Access Now Easy. 2 3 Copyright (C) 2006-2007 Wittawat Yamwong <wittawat@web.de> 4 5 This file is part of the SANE package. 6 7 This program is free software; you can redistribute it and/or 8 modify it under the terms of the GNU General Public License as 9 published by the Free Software Foundation; either version 2 of the 10 License, or (at your option) any later version. 11 12 This program is distributed in the hope that it will be useful, but 13 WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with this program. If not, see <https://www.gnu.org/licenses/>. 19 20 As a special exception, the authors of SANE give permission for 21 additional uses of the libraries contained in this release of SANE. 22 23 The exception is that, if you link a SANE library with other files 24 to produce an executable, this does not by itself cause the 25 resulting executable to be covered by the GNU General Public 26 License. Your use of that executable is in no way restricted on 27 account of linking the SANE library code into it. 28 29 This exception does not, however, invalidate any other reasons why 30 the executable file might be covered by the GNU General Public 31 License. 32 33 If you submit changes to SANE to the maintainers to be included in 34 a subsequent release, you agree by submitting the changes that 35 those changes may be distributed with this exception intact. 36 37 If you write modifications of your own for SANE, it is your choice 38 whether to permit this exception to apply to your modifications. 39 If you do not wish that, delete this exception notice. 40 */ 41 #ifndef PIXMA_IO_H 42 #define PIXMA_IO_H 43 44 /* TODO: move to pixma_common.h, to reduce the number of files */ 45 46 /*! 47 * \defgroup IO IO interface 48 * \brief The IO interface. 49 * 50 * Return value of functions that return \c int if not otherwise specified: 51 * - >= if succeeded 52 * - < 0 if failed (e.g. \c PIXMA_ETIMEDOUT) 53 * . 54 * @{ 55 */ 56 57 /** Timeout for pixma_read() in milliseconds */ 58 #define PIXMA_BULKIN_TIMEOUT 1000 59 /** Timeout for pixma_write() in milliseconds */ 60 #define PIXMA_BULKOUT_TIMEOUT 1000 61 62 63 struct pixma_io_t; 64 struct pixma_config_t; 65 66 /** IO handle */ 67 typedef struct pixma_io_t pixma_io_t; 68 69 70 /** Initialize IO module. It must be called before any other functions in this 71 * module. 72 * \return 0 on success or 73 * - \c PIXMA_ENOMEM 74 * - \c PIXMA_EACCES 75 * - \c PIXMA_EIO */ 76 int pixma_io_init (void); 77 78 /** Shutdown all connections and free resources allocated in this module. */ 79 void pixma_io_cleanup (void); 80 81 /** Find devices currently connected to the computer. 82 * \c devnr passed to functions 83 * - pixma_get_device_config() 84 * - pixma_get_device_id() 85 * - pixma_connect() 86 * . 87 * should be less than the number of devices returned by this function. 88 * \param[in] pixma_devices A \c NULL terminated array of pointers to 89 * array of pixma_config_t which is terminated by setting 90 * pixma_config_t::name to \c NULL. 91 * \return Number of devices found */ 92 unsigned pixma_collect_devices (const char ** conf_devices, 93 const struct pixma_config_t *const 94 pixma_devices[], SANE_Bool local_only); 95 96 /** Get device configuration. */ 97 const struct pixma_config_t *pixma_get_device_config (unsigned devnr); 98 99 /** Get a unique ID of the device \a devnr. */ 100 const char *pixma_get_device_id (unsigned devnr); 101 102 /** Connect to the device and claim the scanner interface. 103 * \param[in] devnr 104 * \param[out] handle 105 * \return 0 on success or 106 * - \c PIXMA_ENODEV the device is gone from the system. 107 * - \c PIXMA_EINVAL \a devnr is invalid. 108 * - \c PIXMA_EBUSY 109 * - \c PIXMA_EACCES 110 * - \c PIXMA_ENOMEM 111 * - \c PIXMA_EIO */ 112 int pixma_connect (unsigned devnr, pixma_io_t ** handle); 113 114 /** Release the scanner interface and disconnect from the device. */ 115 void pixma_disconnect (pixma_io_t *); 116 117 /** Activate connection to scanner */ 118 int pixma_activate (pixma_io_t *); 119 120 /** De-activate connection to scanner */ 121 int pixma_deactivate (pixma_io_t *); 122 123 /** Reset the USB interface. \warning Use with care! */ 124 int pixma_reset_device (pixma_io_t *); 125 126 /** Write data to the device. This function may not be interrupted by signals. 127 * It will return iff 128 * - \a len bytes have been successfully written or 129 * - an error (inclusive timeout) occurred. 130 * . 131 * \note Calling pixma_write(io, buf, n1) and pixma(io, buf+n1, n2) may 132 * not be the same as pixma_write(io, buf, n1+n2) if n1 is not 133 * multiple of the maximum packet size of the endpoint. 134 * \param[in] cmd Data 135 * \param[in] len Length of data 136 * \return Number of bytes successfully written (always = \a len) or 137 * - \c PIXMA_ETIMEDOUT 138 * - \c PIXMA_EIO 139 * - \c PIXMA_ENOMEM 140 * \see #PIXMA_BULKOUT_TIMEOUT */ 141 int pixma_write (pixma_io_t *, const void *cmd, unsigned len); 142 143 /** Read data from the device. This function may not be interrupted by signals. 144 * It will return iff 145 * - \a size bytes have been successfully read, 146 * - a short packet has been read or 147 * - an error (inclusive timeout) occurred. 148 * . 149 * \param[out] buf 150 * \param[in] size of the buffer 151 * \return Number of bytes successfully read. A return value of zero means that 152 * a zero length USB packet was received. Or 153 * - \c PIXMA_ETIMEDOUT 154 * - \c PIXMA_EIO 155 * - \c PIXMA_ENOMEM 156 * \see #PIXMA_BULKIN_TIMEOUT */ 157 int pixma_read (pixma_io_t *, void *buf, unsigned size); 158 159 /** Wait for an interrupt. This function can be interrupted by signals. 160 * \a size should be less than or equal to the maximum packet size. 161 * \param[out] buf 162 * \param[in] size of the buffer 163 * \param[in] timeout in milliseconds; if < 0, wait forever. 164 * \return Number of bytes successfully read or 165 * - \c PIXMA_ETIMEDOUT 166 * - \c PIXMA_EIO 167 * - \c PIXMA_ENOMEM 168 * - \c PIXMA_ECANCELED if it was interrupted by a signal. */ 169 int pixma_wait_interrupt (pixma_io_t *, void *buf, unsigned size, 170 int timeout); 171 172 /** Enable or disable background interrupt monitoring. 173 * Background mode is enabled by default. 174 * \param[in] background if not zero, a URB is submitted in background 175 * for interrupt endpoint. 176 * \return 0 on success or 177 * - \c PIXMA_ENOTSUP 178 * - \c PIXMA_EIO 179 * - \c PIXMA_ENOMEM */ 180 int pixma_set_interrupt_mode (pixma_io_t *, int background); 181 182 /** @} end of IO group */ 183 184 #endif 185