* License: GNU GPL v2 (see License.txt), GNU GPL v3 or proprietary (CommercialLicense.txt)
*/
-#ifndef __HIDDATA_H_INCLUDED__
-#define __HIDDATA_H_INCLUDED__
+#ifndef __HIDUSB_H_INCLUDED__
+#define __HIDUSB_H_INCLUDED__
/*
-General Description:
-This module implements an abstraction layer for data transfer over HID feature
-requests. The implementation uses native Windows functions on Windows so that
-no driver installation is required and libusb on Unix. You must link the
-appropriate libraries in either case: "-lhid -lusb -lsetupapi" on Windows and
-`libusb-config --libs` on Unix.
+This module implements an abstraction layer for data transfer over HID feature requests,
+mainly for use with V-USB based HID custom devices which are not keyboards, mice etc.
+The implementation uses native HID API on Windows, Apple OS X
+or libusb on Linux etc.
+
+Libraries to link are:
+ on Windows XP+ : -lhid -lsetupapi
+ on Linux or other platforms with libusb 0.1: `libusb-config --libs`
+ on Mac OS 10.9+ : IOKit
*/
/* ------------------------------------------------------------------------ */
-#define USBOPEN_SUCCESS 0 /* no error */
-#define USBOPEN_ERR_ACCESS 1 /* not enough permissions to open device */
-#define USBOPEN_ERR_IO 2 /* I/O error */
-#define USBOPEN_ERR_NOTFOUND 3 /* device not found */
+#define USBHID_OK 0 /* no error */
+#define USBHID_ERR_ACCESS 1 /* access or permissions error */
+#define USBHID_ERR_IO 2 /* I/O error */
+#define USBHID_ERR_NOTFOUND 3 /* device not found */
+#define USBHID_ERR_BAD_ARG 20 /* invalid parameter */
+#define USBHID_ERR_INTERNAL 23 /* not implemented, not supported... */
+#define USBHID_ERR_IO_USB 24 /* I/O error at usb layer */
+#define USBHID_ERR_IO_HID 25 /* I/O error at hid layer */
+#define USBHID_ERR_UNKNOWN -1 /* whatever */
+
/* ------------------------------------------------------------------------ */
+/* USBDEVHANDLE: Opaque handle representing the USB HID device.
+ */
struct usbDevice;
typedef struct usbDevice usbDevice_t;
-typedef usbDevice_t *USBDEVHANDLE;
+typedef struct usbDevice *USBDEVHANDLE;
-/* Opaque data type representing the USB device. This can be a Windows handle
- * or a libusb handle, depending on the backend implementation.
- */
/* ------------------------------------------------------------------------ */
* Each found device is opened and the callback will be called.
* The callback can probe the device and close it or keep open.
* If the callback returns 0, enumeration stops, else it goes on.
- * @returns 0 if some devices were found or error code otherwise.
+ * @param usbhidEnumFunc: callback function
+ * @param context: context pointer for the callback
+ * @return 0 if some devices were found or error code otherwise.
*/
int usbhidEnumDevices(int vendorID, int productID, void *context,
int (*usbhidEnumFunc)(USBDEVHANDLE usbh, void *ctx));
/*
- * Close USB device handle opened with usbhidEnumDevices
+ * Close USBDEVHANDLE passed by usbhidEnumDevices
*/
void usbhidCloseDevice(USBDEVHANDLE usbh);
int usbhidGetVendorString(USBDEVHANDLE usbh, char *buffer, int len);
int usbhidGetProductString(USBDEVHANDLE usbh, char *buffer, int len);
-int usbhidSetReport(usbDevice_t *device, char *buffer, int len);
-/* This function sends a feature report to the device. The report ID must be
- * in the first byte of buffer and the length 'len' of the report is specified
- * including this report ID. If no report IDs are used, buffer[0] must be set
- * to 0 (dummy report ID).
- * Returns: 0 on success, an error code otherwise.
+/* Send a feature report to the device. The report ID must be
+ * in the first byte of buffer and the length 'len' of the report buffer
+ * includes this report ID. If the device does not specify report IDs,
+ * buffer[0] must be set to 0.
+ * @return: 0 on success, an error code otherwise.
*/
+int usbhidSetReport(USBDEVHANDLE usbh, char *buffer, int len);
-int usbhidGetReport(usbDevice_t *device, int reportID, char *buffer, int *len);
-/* This function obtains a feature report from the device. The requested
- * report-ID is passed in 'reportID'. The caller must pass a buffer of the size
- * of the expected report in 'buffer' and initialize the variable pointed to by
+/* Read a feature report from the device.
+ * The requested report ID is passed in 'reportID' parameter and returned
+ * in the 1st byte of the data.
+ * The caller must pass a buffer of the size of the expected report in 'buffer'
+ * including the report id byte, and initialize the variable pointed to by
* 'len' to the total size of this buffer. Upon successful return, the report
* (prefixed with the report-ID) is in 'buffer' and the actual length of the
* report is returned in '*len'.
* Returns: 0 on success, an error code otherwise.
*/
+int usbhidGetReport(USBDEVHANDLE usbh, int reportID, char *buffer, int *len);
+
+
+/**
+ * Return description of error code
+ * TODO? return error descr. of underlying libusb or hid layer too?
+ */
+int usbhidStrerror_r( int err, char *buf, int len);
/* ------------------------------------------------------------------------ */
-#endif /* __HIDDATA_H_INCLUDED__ */
+#endif /* __HIDUSB_H_INCLUDED__ */
projects / usb-relay-hid.git / blobdiff