SANEI  1.2.1.189-7ab850
sanei_usb.h
Go to the documentation of this file.
1 /* sane - Scanner Access Now Easy.
2  Copyright (C) 2001, 2002 Henning Meier-Geinitz
3  Copyright (C) 2003, 2005 Rene Rebe (sanei_read_int,sanei_set_timeout)
4  Copyright (C) 2008 m. allan noah (sanei_usb_clear_halt)
5  Copyright (C) 2011 Reinhold Kainhofer (sanei_usb_set_endpoint)
6  This file is part of the SANE package.
7 
8  SANE is free software; you can redistribute it and/or modify it
9  under the terms of the GNU General Public License as published by
10  the Free Software Foundation; either version 2 of the License, or
11  (at your option) any later version.
12 
13  SANE is distributed in the hope that it will be useful, but WITHOUT
14  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
16  License for more details.
17 
18  You should have received a copy of the GNU General Public License
19  along with sane; see the file COPYING.
20  If not, see <https://www.gnu.org/licenses/>.
21 
22  As a special exception, the authors of SANE give permission for
23  additional uses of the libraries contained in this release of SANE.
24 
25  The exception is that, if you link a SANE library with other files
26  to produce an executable, this does not by itself cause the
27  resulting executable to be covered by the GNU General Public
28  License. Your use of that executable is in no way restricted on
29  account of linking the SANE library code into it.
30 
31  This exception does not, however, invalidate any other reasons why
32  the executable file might be covered by the GNU General Public
33  License.
34 
35  If you submit changes to SANE to the maintainers to be included in
36  a subsequent release, you agree by submitting the changes that
37  those changes may be distributed with this exception intact.
38 
39  If you write modifications of your own for SANE, it is your choice
40  whether to permit this exception to apply to your modifications.
41  If you do not wish that, delete this exception notice.
42 */
43 
63 #ifndef sanei_usb_h
64 #define sanei_usb_h
65 
66 #include "../include/sane/config.h"
67 #include "../include/sane/sane.h"
68 
69 #include <stdlib.h> /* for size_t */
70 
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74 
75 /* USB spec defines */
76 #ifndef USB_CLASS_PER_INTERFACE
77 /* Also defined in libusb */
79 /* @{ */
80 #define USB_CLASS_PER_INTERFACE 0x00
81 #define USB_CLASS_AUDIO 0x01
82 #define USB_CLASS_COMM 0x02
83 #define USB_CLASS_HID 0x03
84 #define USB_CLASS_PRINTER 0x07
85 #define USB_CLASS_MASS_STORAGE 0x08
86 #define USB_CLASS_HUB 0x09
87 #define USB_CLASS_DATA 0x0a
88 #define USB_CLASS_VENDOR_SPEC 0xff
89 /* @} */
90 
92 /* @{ */
93 #define USB_DT_DEVICE 0x01
94 #define USB_DT_CONFIG 0x02
95 #define USB_DT_STRING 0x03
96 #define USB_DT_INTERFACE 0x04
97 #define USB_DT_ENDPOINT 0x05
98 #define USB_DT_HID 0x21
99 #define USB_DT_REPORT 0x22
100 #define USB_DT_PHYSICAL 0x23
101 #define USB_DT_HUB 0x29
102 /* @} */
103 
105 /* @{ */
106 #define USB_DT_DEVICE_SIZE 18
107 #define USB_DT_CONFIG_SIZE 9
108 #define USB_DT_INTERFACE_SIZE 9
109 #define USB_DT_ENDPOINT_SIZE 7
110 #define USB_DT_ENDPOINT_AUDIO_SIZE 9
111 #define USB_DT_HUB_NONVAR_SIZE 7
112 /* @} */
113 
115 /* @{ */
116 #define USB_ENDPOINT_ADDRESS_MASK 0x0f
117 #define USB_ENDPOINT_DIR_MASK 0x80
118 #define USB_ENDPOINT_TYPE_MASK 0x03
119 #define USB_ENDPOINT_TYPE_CONTROL 0
120 #define USB_ENDPOINT_TYPE_ISOCHRONOUS 1
121 #define USB_ENDPOINT_TYPE_BULK 2
122 #define USB_ENDPOINT_TYPE_INTERRUPT 3
123 /* @} */
124 
126 /* @{ */
127 #define USB_REQ_GET_STATUS 0x00
128 #define USB_REQ_CLEAR_FEATURE 0x01
129 #define USB_REQ_SET_FEATURE 0x03
130 #define USB_REQ_SET_ADDRESS 0x05
131 #define USB_REQ_GET_DESCRIPTOR 0x06
132 #define USB_REQ_SET_DESCRIPTOR 0x07
133 #define USB_REQ_GET_CONFIGURATION 0x08
134 #define USB_REQ_SET_CONFIGURATION 0x09
135 #define USB_REQ_GET_INTERFACE 0x0A
136 #define USB_REQ_SET_INTERFACE 0x0B
137 #define USB_REQ_SYNCH_FRAME 0x0C
138 /* @} */
139 
141 /* @{ */
142 #define USB_TYPE_STANDARD (0x00 << 5)
143 #define USB_TYPE_CLASS (0x01 << 5)
144 #define USB_TYPE_VENDOR (0x02 << 5)
145 #define USB_TYPE_RESERVED (0x03 << 5)
146 /* @} */
147 
149 /* @{ */
150 #define USB_RECIP_DEVICE 0x00
151 #define USB_RECIP_INTERFACE 0x01
152 #define USB_RECIP_ENDPOINT 0x02
153 #define USB_RECIP_OTHER 0x03
154 /* @} */
155 
156 #endif /* not USB_CLASS_PER_INTERFACE */
157 
158 /* Not defined in libsub */
160 /* @{ */
161 #define USB_TYPE_MASK (0x03 << 5)
162 #define USB_RECIP_MASK 0x1f
163 /* @} */
164 
166 /* @{ */
167 #define USB_DIR_OUT 0x00
168 #define USB_DIR_IN 0x80
169 /* @} */
170 
172 struct sanei_usb_dev_descriptor
173 {
174  SANE_Byte desc_type;
175  unsigned int bcd_usb;
176  unsigned int bcd_dev;
177  SANE_Byte dev_class;
178  SANE_Byte dev_sub_class;
179  SANE_Byte dev_protocol;
180  SANE_Byte max_packet_size;
181 };
182 
201 extern SANE_Status sanei_usb_testing_enable_replay(SANE_String_Const path,
202  int development_mode);
203 
212 extern SANE_Status sanei_usb_testing_enable_record(SANE_String_Const path,
213  SANE_String_Const be_name);
214 
220 extern SANE_String sanei_usb_testing_get_backend();
221 
226 
239 
245 extern void sanei_usb_testing_record_message(SANE_String_Const message);
246 
251 extern void sanei_usb_init (void);
252 
258 extern void sanei_usb_exit (void);
259 
264 extern void sanei_usb_scan_devices (void);
265 
278 SANE_Status
279 sanei_usb_get_vendor_product_byname (SANE_String_Const devname,
280  SANE_Word * vendor, SANE_Word * product);
281 
296 extern SANE_Status
297 sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word * vendor,
298  SANE_Word * product);
299 
311 extern SANE_Status
312 sanei_usb_find_devices (SANE_Int vendor, SANE_Int product,
313  SANE_Status (*attach) (SANE_String_Const devname));
314 
335 extern SANE_Status sanei_usb_open (SANE_String_Const devname, SANE_Int * dn);
336 
349 extern void sanei_usb_set_endpoint (SANE_Int dn, SANE_Int ep_type, SANE_Int ep);
350 
362 extern SANE_Int sanei_usb_get_endpoint (SANE_Int dn, SANE_Int ep_type);
363 
368 extern void sanei_usb_close (SANE_Int dn);
369 
374 extern void sanei_usb_set_timeout (SANE_Int timeout);
375 
378 #define HAVE_SANEI_USB_SET_TIMEOUT
379 
384 extern SANE_Status sanei_usb_clear_halt (SANE_Int dn);
385 
388 #define HAVE_SANEI_USB_CLEAR_HALT
389 
394 extern SANE_Status sanei_usb_reset (SANE_Int dn);
395 
412 extern SANE_Status
413 sanei_usb_read_bulk (SANE_Int dn, SANE_Byte * buffer, size_t * size);
414 
429 extern SANE_Status
430 sanei_usb_write_bulk (SANE_Int dn, const SANE_Byte * buffer, size_t * size);
431 
456 extern SANE_Status
457 sanei_usb_control_msg (SANE_Int dn, SANE_Int rtype, SANE_Int req,
458  SANE_Int value, SANE_Int index, SANE_Int len,
459  SANE_Byte * data);
460 
478 extern SANE_Status
479 sanei_usb_read_int (SANE_Int dn, SANE_Byte * buffer, size_t * size);
480 
497 extern void
499  SANE_Status (*attach) (const char *dev));
500 
516 extern SANE_Status
517 sanei_usb_set_configuration (SANE_Int dn, SANE_Int configuration);
518 
534 extern SANE_Status
535 sanei_usb_claim_interface (SANE_Int dn, SANE_Int interface_number);
536 
552 extern SANE_Status
553 sanei_usb_release_interface (SANE_Int dn, SANE_Int interface_number);
554 
570 extern SANE_Status
571 sanei_usb_set_altinterface (SANE_Int dn, SANE_Int alternate);
572 
589 extern SANE_Status
590 sanei_usb_get_descriptor( SANE_Int dn, struct sanei_usb_dev_descriptor *desc );
591 
592 #ifdef __cplusplus
593 } // extern "C"
594 #endif
595 
596 /*------------------------------------------------------*/
597 #endif /* sanei_usb_h */
SANE_Status sanei_usb_read_int(SANE_Int dn, SANE_Byte *buffer, size_t *size)
Initiate a interrupt transfer read.
void sanei_usb_attach_matching_devices(const char *name, SANE_Status(*attach)(const char *dev))
Expand device name patterns into a list of devices.
SANE_Status sanei_usb_testing_enable_replay(SANE_String_Const path, int development_mode)
Initialize sanei_usb for replay testing.
void sanei_usb_testing_record_message(SANE_String_Const message)
Records a debug message in the captured USB data if testing mode is enabled.
SANE_Status sanei_usb_open(SANE_String_Const devname, SANE_Int *dn)
Open a USB device.
SANE_Status sanei_usb_release_interface(SANE_Int dn, SANE_Int interface_number)
Initiate release interface.
void sanei_usb_set_endpoint(SANE_Int dn, SANE_Int ep_type, SANE_Int ep)
Set the endpoint for the USB communication.
SANE_Status sanei_usb_write_bulk(SANE_Int dn, const SANE_Byte *buffer, size_t *size)
Initiate a bulk transfer write.
SANE_Bool sanei_usb_is_replay_mode_enabled()
Returns SANE_TRUE if replay testing mode is enabled, i.e.
SANE_Status sanei_usb_clear_halt(SANE_Int dn)
Clear halt condition on bulk endpoints.
void sanei_usb_exit(void)
End sanei_usb use, freeing resources when needed.
SANE_String sanei_usb_testing_get_backend()
Returns backend name for testing.
void sanei_usb_init(void)
Initialize sanei_usb.
SANE_Status sanei_usb_testing_enable_record(SANE_String_Const path, SANE_String_Const be_name)
Initialize sanei_usb for recording.
SANE_Status sanei_usb_control_msg(SANE_Int dn, SANE_Int rtype, SANE_Int req, SANE_Int value, SANE_Int index, SANE_Int len, SANE_Byte *data)
Send/receive a control message to/from a USB device.
SANE_Status sanei_usb_get_vendor_product_byname(SANE_String_Const devname, SANE_Word *vendor, SANE_Word *product)
Get the vendor and product ids by device name.
SANE_Int sanei_usb_get_endpoint(SANE_Int dn, SANE_Int ep_type)
Retrieve the endpoint used for the USB communication.
SANE_Status sanei_usb_find_devices(SANE_Int vendor, SANE_Int product, SANE_Status(*attach)(SANE_String_Const devname))
Find devices that match given vendor and product ids.
SANE_Status sanei_usb_get_vendor_product(SANE_Int dn, SANE_Word *vendor, SANE_Word *product)
Get the vendor and product ids.
void sanei_usb_close(SANE_Int dn)
Close a USB device.
void sanei_usb_scan_devices(void)
Search for USB devices.
SANE_Status sanei_usb_get_descriptor(SANE_Int dn, struct sanei_usb_dev_descriptor *desc)
Get some information from the device descriptor.
void sanei_usb_testing_record_clear()
Clears currently recorded data.
SANE_Status sanei_usb_set_altinterface(SANE_Int dn, SANE_Int alternate)
Initiate a set altinterface.
void sanei_usb_set_timeout(SANE_Int timeout)
Set the libusb timeout for bulk and interrupt reads.
SANE_Status sanei_usb_claim_interface(SANE_Int dn, SANE_Int interface_number)
Initiate claim interface.
SANE_Status sanei_usb_set_configuration(SANE_Int dn, SANE_Int configuration)
Initiate set configuration.
SANE_Status sanei_usb_read_bulk(SANE_Int dn, SANE_Byte *buffer, size_t *size)
Initiate a bulk transfer read.
SANE_Status sanei_usb_reset(SANE_Int dn)
Reset device.