summaryrefslogtreecommitdiff
path: root/include/sane/sanei_scsi.h
blob: d69fd0f62e85b66db89a262cfd56bd0e3a3909b3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
/* 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

#include <sys/types.h>

#include <sane/sane.h>
#include <sane/config.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 */