1 /* sane - Scanner Access Now Easy. 2 Copyright (C) 1996, 1997 David Mosberger-Tang 3 This file is part of the SANE package. 4 5 SANE is free software; you can redistribute it and/or modify it 6 under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 2 of the License, or 8 (at your option) any later version. 9 10 SANE is distributed in the hope that it will be useful, but WITHOUT 11 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 12 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public 13 License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with sane; see the file COPYING. 17 If not, see <https://www.gnu.org/licenses/>. 18 19 As a special exception, the authors of SANE give permission for 20 additional uses of the libraries contained in this release of SANE. 21 22 The exception is that, if you link a SANE library with other files 23 to produce an executable, this does not by itself cause the 24 resulting executable to be covered by the GNU General Public 25 License. Your use of that executable is in no way restricted on 26 account of linking the SANE library code into it. 27 28 This exception does not, however, invalidate any other reasons why 29 the executable file might be covered by the GNU General Public 30 License. 31 32 If you submit changes to SANE to the maintainers to be included in 33 a subsequent release, you agree by submitting the changes that 34 those changes may be distributed with this exception intact. 35 36 If you write modifications of your own for SANE, it is your choice 37 whether to permit this exception to apply to your modifications. 38 If you do not wish that, delete this exception notice. 39 */ 40 41 /** @file sanei_scsi.h 42 * Generic interface to SCSI drivers. 43 * @sa sanei_usb.h, sanei_ab306.h,sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, 44 * and man sane-scsi(5) for user-oriented documentation 45 */ 46 47 #ifndef sanei_scsi_h 48 #define sanei_scsi_h 49 50 #include <sys/types.h> 51 52 #include <sane/sane.h> 53 #include <sane/config.h> 54 55 /** Sense handler 56 * 57 * The sense handler can be implemented in backends. It's for deciding 58 * which sense codes should be considered an error and which shouldn't. 59 * 60 * @param fd file descriptor 61 * @param sense_buffer pointer to buffer containing sense codes 62 * @param arg pointer to data buffer 63 * 64 * @return 65 * - SANE_STATUS_GOOD - on success (sense isn't regarded as error) 66 * - any other status if sense code is regarded as error 67 */ 68 typedef SANE_Status (*SANEI_SCSI_Sense_Handler) (int fd, 69 u_char *sense_buffer, 70 void *arg); 71 /** Maximum size of a SCSI request 72 */ 73 extern int sanei_scsi_max_request_size; 74 75 /** Find SCSI devices. 76 * 77 * Find each SCSI device that matches the pattern specified by the 78 * arguments. String arguments can be "omitted" by passing NULL, 79 * integer arguments can be "omitted" by passing -1. 80 * 81 * Example: vendor="HP" model=NULL, type=NULL, bus=3, id=-1, lun=-1 would 82 * attach all HP devices on SCSI bus 3. 83 * 84 * @param vendor 85 * @param model 86 * @param type 87 * @param bus 88 * @param channel 89 * @param id 90 * @param lun 91 * @param attach callback invoked once for each device, dev is the real devicename (passed to attach callback) 92 * 93 */ 94 extern void sanei_scsi_find_devices (const char *vendor, const char *model, 95 const char *type, 96 int bus, int channel, int id, int lun, 97 SANE_Status (*attach) (const char *dev)); 98 99 100 /** Open a SCSI device 101 * 102 * Opens a SCSI device by its device filename and returns a file descriptor. 103 * If it's necessary to adjust the SCSI buffer size, use 104 * sanei_scsi_open_extended(). 105 * 106 * @param device_name name of the devicefile, e.g. "/dev/sg0" 107 * @param fd file descriptor 108 * @param sense_handler called whenever the SCSI driver returns a sense buffer 109 * @param sense_arg pointer to data for the sense handler 110 * 111 * @return 112 * - SANE_STATUS_GOOD - on success 113 * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to 114 * permissions 115 * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) 116 * - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occurred 117 * 118 * @sa sanei_scsi_open_extended(), HAVE_SANEI_SCSI_OPEN_EXTENDED 119 */ 120 extern SANE_Status sanei_scsi_open (const char * device_name, int * fd, 121 SANEI_SCSI_Sense_Handler sense_handler, 122 void *sense_arg); 123 124 /** Open a SCSI device and set the buffer size 125 * 126 * The extended open call allows a backend to ask for a specific buffer 127 * size. sanei_scsi_open_extended() tries to allocate a buffer of the size 128 * given by *buffersize upon entry to this function. If 129 * sanei_scsi_open_extended returns successfully, *buffersize contains the 130 * available buffer size. This value may be both smaller or larger than the 131 * value requested by the backend; it can even be zero. The backend must 132 * decide, if it got enough buffer memory to work. 133 * 134 * Note that the value of *buffersize may differ for different files. 135 * 136 * @param device_name name of the devicefile, e.g. "/dev/sg0" 137 * @param fd file descriptor 138 * @param sense_handler called whenever the SCSI driver returns a sense buffer 139 * @param sense_arg pointer to data for the sense handler 140 * @param buffersize size of the SCAI request buffer (in bytes) 141 * 142 * @return 143 * - SANE_STATUS_GOOD - on success 144 * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to 145 * permissions 146 * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) 147 * - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occurred 148 * 149 * @sa sanei_scsi_open(), HAVE_SANEI_SCSI_OPEN_EXTENDED 150 */ 151 extern SANE_Status sanei_scsi_open_extended ( 152 const char * device_name, int * fd, 153 SANEI_SCSI_Sense_Handler sense_handler, 154 void *sense_arg, int *buffersize); 155 156 /** Do we have sanei_scsi_open_extended()? 157 * 158 * Let backends decide, which open call to use: if 159 * HAVE_SANEI_SCSI_OPEN_EXTENDED is defined, sanei_scsi_open_extended may be 160 * used. May also be used to decide, if sanei_scsi_req_flush_all or 161 * sanei_scsi_req_flush_all_extended() should be used. 162 * 163 * @sa sanei_scsi_open(), sanei_scsi_open_extended() 164 */ 165 #define HAVE_SANEI_SCSI_OPEN_EXTENDED 166 167 /** Enqueue SCSI command 168 * 169 * One or more scsi commands can be enqueued by calling sanei_scsi_req_enter(). 170 * 171 * NOTE: Some systems may not support multiple outstanding commands. On such 172 * systems, sanei_scsi_req_enter() may block. In other words, it is not proper 173 * to assume that enter() is a non-blocking routine. 174 * 175 * @param fd file descriptor 176 * @param src pointer to the SCSI command and associated write data (if any) 177 * @param src_size length of the command and data 178 * @param dst pointer to a buffer in which data is returned; NULL if no data is 179 * returned 180 * @param dst_size on input, the size of the buffer pointed to by dst, on exit, 181 * set to the number of bytes returned in the buffer (which is less than or equal 182 * to the buffer size; may be NULL if no data is expected 183 * @param idp pointer to a void* that uniquely identifies the entered request 184 * 185 * @return 186 * - SANE_STATUS_GOOD - on success 187 * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver 188 * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) 189 * - SANE_STATUS_INVAL - if a locking or an unknown error occurred 190 * @sa sanei_scsi_req_enter2() 191 * 192 */ 193 extern SANE_Status sanei_scsi_req_enter (int fd, 194 const void * src, size_t src_size, 195 void * dst, size_t * dst_size, 196 void **idp); 197 198 /** Enqueue SCSI command and separated data 199 * 200 * Same as sanei_scsi_req_enter(), but with separate buffers for the SCSI 201 * command and for the data to be sent to the device. 202 * 203 * With sanei_scsi_req_enter(), the length of the SCSI command block must be 204 * guessed. While that works in most cases, Canon scanners for example use the 205 * vendor specific commands 0xd4, 0xd5 and 0xd6. The Canon scanners want to 206 * get 6 byte command blocks for these commands, but sanei_scsi_req_enter() and 207 * sanei_scsi_cmd() send 12 bytes. 208 * 209 * If dst_size and *dst_size are non-zero, a "read command" (ie, data transfer 210 * from the device to the host) is assumed. 211 * 212 * @param fd file descriptor 213 * @param cmd pointer to SCSI command 214 * @param cmd_size size of the command 215 * @param src pointer to the buffer with data to be sent to the scanner 216 * @param src_size size of src buffer 217 * @param dst pointer to a buffer in which data is returned; NULL if no data is 218 * returned 219 * @param dst_size on input, the size of the buffer pointed to by dst, on exit, 220 * set to the number of bytes returned in the buffer (which is less than or equal 221 * to the buffer size; may be NULL if no data is expected 222 * @param idp pointer to a void* that uniquely identifies the entered request 223 * @return 224 * - SANE_STATUS_GOOD - on success 225 * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver 226 * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) 227 * - SANE_STATUS_INVAL - if a locking or an unknown error occurred 228 * @sa sanei_scsi_req_enter() 229 */ 230 extern SANE_Status sanei_scsi_req_enter2 (int fd, 231 const void * cmd, size_t cmd_size, 232 const void * src, size_t src_size, 233 void * dst, size_t * dst_size, 234 void **idp); 235 236 /** Wait for SCSI command 237 * 238 * Wait for the completion of the SCSI command with id ID. 239 * 240 * @param id id used in sanei_scsi_req_enter() 241 * 242 * @return 243 * - SANE_STATUS_GOOD - on success 244 * - SANE_STATUS_DEVICE_BUSY - if the device is busy (try again later) 245 * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver 246 */ 247 extern SANE_Status sanei_scsi_req_wait (void *id); 248 249 /** Send SCSI command 250 * 251 * This is a convenience function that is equivalent to a pair of 252 * sanei_scsi_req_enter()/sanei_scsi_req_wait() calls. 253 * 254 * @param fd file descriptor 255 * @param src pointer to the SCSI command and associated write data (if any) 256 * @param src_size length of the command and data 257 * @param dst pointer to a buffer in which data is returned; NULL if no data is 258 * returned 259 * @param dst_size on input, the size of the buffer pointed to by dst, on exit, 260 * set to the number of bytes returned in the buffer (which is less than or equal 261 * to the buffer size; may be NULL if no data is expected 262 * 263 * @return 264 * - SANE_STATUS_GOOD - on success 265 * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver 266 * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) 267 * - SANE_STATUS_INVAL - if a locking or an unknown error occurred 268 * 269 * @sa sanei_scsi_cmd2(), sanei_scsi_req_enter(), sanei_scsi_req_wait() 270 */ 271 extern SANE_Status sanei_scsi_cmd (int fd, 272 const void * src, size_t src_size, 273 void * dst, size_t * dst_size); 274 275 /** Send SCSI command and separated data 276 * 277 * This is a convenience function that is equivalent to a pair of 278 * sanei_scsi_req_enter2()/sanei_scsi_req_wait() calls. 279 * 280 * @param fd file descriptor 281 * @param cmd pointer to SCSI command 282 * @param cmd_size size of the command 283 * @param src pointer to the buffer with data to be sent to the scanner 284 * @param src_size size of src buffer 285 * @param dst pointer to a buffer in which data is returned; NULL if no data is 286 * returned 287 * @param dst_size on input, the size of the buffer pointed to by dst, on exit, 288 * set to the number of bytes returned in the buffer (which is less than or equal 289 * to the buffer size; may be NULL if no data is expected 290 * @return 291 * - SANE_STATUS_GOOD - on success 292 * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver 293 * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory) 294 * - SANE_STATUS_INVAL - if a locking or an unknown error occurred 295 * 296 * @sa sanei_scsi_cmd(), sanei_scsi_req_enter(), sanei_scsi_req_wait() 297 */ 298 extern SANE_Status sanei_scsi_cmd2 (int fd, 299 const void * cmd, size_t cmd_size, 300 const void * src, size_t src_size, 301 void * dst, size_t * dst_size); 302 303 /** Flush queue 304 * 305 * Flush all pending SCSI commands. This function work only, if zero or one 306 * SCSI file handles are open. 307 * 308 * @sa sanei_scsi_req_flush_all_extended() 309 */ 310 extern void sanei_scsi_req_flush_all (void); 311 312 /** Flush queue for handle 313 * 314 * Flush all SCSI commands pending for one handle 315 * 316 * @param fd file descriptor 317 * 318 * @sa sanei_scsi_req_flush_all() 319 */ 320 extern void sanei_scsi_req_flush_all_extended (int fd); 321 322 /** Close a SCSI device 323 * 324 * @param fd file descriptor 325 * 326 */ 327 extern void sanei_scsi_close (int fd); 328 329 #endif /* sanei_scsi_h */ 330