CTHN.de - LEDCube - commandline client
opendevice.h
Go to the documentation of this file.
00001 /* Name: opendevice.h
00002  * Project: V-USB host-side library
00003  * Author: Christian Starkjohann
00004  * Creation Date: 2008-04-10
00005  * Tabsize: 4
00006  * Copyright: (c) 2008 by OBJECTIVE DEVELOPMENT Software GmbH
00007  * License: GNU GPL v2 (see License.txt), GNU GPL v3 or proprietary (CommercialLicense.txt)
00008  * This Revision: $Id: opendevice.h 755 2009-08-03 17:01:21Z cs $
00009  */
00010 
00011 /*
00012 General Description:
00013 This module offers additional functionality for host side drivers based on
00014 libusb or libusb-win32. It includes a function to find and open a device
00015 based on numeric IDs and textual description. It also includes a function to
00016 obtain textual descriptions from a device.
00017 
00018 To use this functionality, simply copy opendevice.c and opendevice.h into your
00019 project and add them to your Makefile. You may modify and redistribute these
00020 files according to the GNU General Public License (GPL) version 2 or 3.
00021 */
00022 
00023 #ifndef __OPENDEVICE_H_INCLUDED__
00024 #define __OPENDEVICE_H_INCLUDED__
00025 
00026 #include <usb.h>    /* this is libusb, see http://libusb.sourceforge.net/ */
00027 #include <stdio.h>
00028 
00029 int usbGetStringAscii(usb_dev_handle *dev, int index, char *buf, int buflen);
00030 /* This function gets a string descriptor from the device. 'index' is the
00031  * string descriptor index. The string is returned in ISO Latin 1 encoding in
00032  * 'buf' and it is terminated with a 0-character. The buffer size must be
00033  * passed in 'buflen' to prevent buffer overflows. A libusb device handle
00034  * must be given in 'dev'.
00035  * Returns: The length of the string (excluding the terminating 0) or
00036  * a negative number in case of an error. If there was an error, use
00037  * usb_strerror() to obtain the error message.
00038  */
00039 
00040 int usbOpenDevice(usb_dev_handle **device, int vendorID, char *vendorNamePattern, int productID, char *productNamePattern, char *serialNamePattern, FILE *printMatchingDevicesFp, FILE *warningsFp);
00041 /* This function iterates over all devices on all USB busses and searches for
00042  * a device. Matching is done first by means of Vendor- and Product-ID (passed
00043  * in 'vendorID' and 'productID'. An ID of 0 matches any numeric ID (wildcard).
00044  * When a device matches by its IDs, matching by names is performed. Name
00045  * matching can be done on textual vendor name ('vendorNamePattern'), product
00046  * name ('productNamePattern') and serial number ('serialNamePattern'). A
00047  * device matches only if all non-null pattern match. If you don't care about
00048  * a string, pass NULL for the pattern. Patterns are Unix shell style pattern:
00049  * '*' stands for 0 or more characters, '?' for one single character, a list
00050  * of characters in square brackets for a single character from the list
00051  * (dashes are allowed to specify a range) and if the lis of characters begins
00052  * with a caret ('^'), it matches one character which is NOT in the list.
00053  * Other parameters to the function: If 'warningsFp' is not NULL, warning
00054  * messages are printed to this file descriptor with fprintf(). If
00055  * 'printMatchingDevicesFp' is not NULL, no device is opened but matching
00056  * devices are printed to the given file descriptor with fprintf().
00057  * If a device is opened, the resulting USB handle is stored in '*device'. A
00058  * pointer to a "usb_dev_handle *" type variable must be passed here.
00059  * Returns: 0 on success, an error code (see defines below) on failure.
00060  */
00061 
00062 /* usbOpenDevice() error codes: */
00063 #define USBOPEN_SUCCESS         0   /* no error */
00064 #define USBOPEN_ERR_ACCESS      1   /* not enough permissions to open device */
00065 #define USBOPEN_ERR_IO          2   /* I/O error */
00066 #define USBOPEN_ERR_NOTFOUND    3   /* device not found */
00067 
00068 
00069 /* Obdev's free USB IDs, see USB-IDs-for-free.txt for details */
00070 
00071 #define USB_VID_OBDEV_SHARED        5824    /* obdev's shared vendor ID */
00072 #define USB_PID_OBDEV_SHARED_CUSTOM 1500    /* shared PID for custom class devices */
00073 #define USB_PID_OBDEV_SHARED_HID    1503    /* shared PID for HIDs except mice & keyboards */
00074 #define USB_PID_OBDEV_SHARED_CDCACM 1505    /* shared PID for CDC Modem devices */
00075 #define USB_PID_OBDEV_SHARED_MIDI   1508    /* shared PID for MIDI class devices */
00076 
00077 #endif /* __OPENDEVICE_H_INCLUDED__ */
 All Files Functions Variables Defines