commandline/hiddata.h

   1 /* Name: hiddata.h $$$$$$$$$$$$$$$$$$$$$$$$$
   2  * Author: Christian Starkjohann
   3  * Creation Date: 2008-04-11
   4  * Tabsize: 4
   5  * Copyright: (c) 2008 by OBJECTIVE DEVELOPMENT Software GmbH
   6  * License: GNU GPL v2 (see License.txt), GNU GPL v3 or proprietary (CommercialLicense.txt)
   7  */
   8
   9 #ifndef __HIDUSB_H_INCLUDED__
  10 #define __HIDUSB_H_INCLUDED__
  11
  12 /*
  13 This module implements an abstraction layer for data transfer over HID feature requests,
  14 mainly for use with V-USB based HID custom devices which are not keyboards, mice etc.
  15 The implementation uses native HID API on Windows, Apple OS X
  16 or libusb on Linux etc.
  17
  18 Libraries to link are:
  19   on Windows XP+ : -lhid -lsetupapi
  20   on Linux or other platforms with libusb 0.1: `libusb-config --libs`
  21   on Mac OS 10.9+ : IOKit
  22 */
  23
  24 /* ------------------------------------------------------------------------ */
  25
  26 #define USBHID_OK              0   /* no error */
  27 #define USBHID_ERR_ACCESS      1   /* access or permissions error */
  28 #define USBHID_ERR_IO          2   /* I/O error */
  29 #define USBHID_ERR_NOTFOUND    3   /* device not found */
  30 #define USBHID_ERR_BAD_ARG     20  /* invalid parameter */
  31 #define USBHID_ERR_INTERNAL    23  /* not implemented, not supported... */
  32 #define USBHID_ERR_IO_USB      24  /* I/O error at usb layer  */
  33 #define USBHID_ERR_IO_HID      25  /* I/O error at hid layer */
  34 #define USBHID_ERR_UNKNOWN     -1  /* whatever */
  35
  36
  37 /* ------------------------------------------------------------------------ */
  38
  39 /* USBDEVHANDLE: Opaque handle representing the USB HID device.
  40  */
  41 struct usbDevice;
  42 typedef struct usbDevice    usbDevice_t;
  43 typedef struct usbDevice    *USBDEVHANDLE;
  44
  45
  46 /* ------------------------------------------------------------------------ */
  47
  48 /* @func usbhidEnumDevices
  49  * Enumerates USB HID devices, filtered by USB vendorID and productID.
  50  * Each found device is opened and the callback will be called.
  51  * The callback can probe the device and close it or keep open.
  52  * If the callback returns 0, enumeration stops, else it goes on.
  53  * @param usbhidEnumFunc: callback function
  54  * @param context: context pointer for the callback
  55  * @return 0 if some devices were found or error code otherwise.
  56  */
  57 int usbhidEnumDevices(int vendorID, int productID, void *context,
  58                       int (*usbhidEnumFunc)(USBDEVHANDLE usbh, void *ctx));
  59
  60 /*
  61  * Close USBDEVHANDLE passed by usbhidEnumDevices
  62  */
  63 void usbhidCloseDevice(USBDEVHANDLE usbh);
  64
  65 /*
  66  * Read HID vendor and product strings as ASCII null terminated strings
  67  * Returns 0 on success, error code if error occured or the buffer is too short
  68  * Any non-ascii characters in the strings will be replaced to '?'
  69  */
  70 int usbhidGetVendorString(USBDEVHANDLE usbh, char *buffer, int len);
  71 int usbhidGetProductString(USBDEVHANDLE usbh, char *buffer, int len);
  72
  73 /* Send a feature report to the device. The report ID must be
  74  * in the first byte of buffer and the length 'len' of the report buffer
  75  * includes this report ID. If the device does not specify report IDs,
  76  *  buffer[0] must be set to 0.
  77  * @return: 0 on success, an error code otherwise.
  78  */
  79 int usbhidSetReport(USBDEVHANDLE usbh, char *buffer, int len);
  80
  81 /* Read a feature report from the device.
  82  * The requested report ID is passed in 'reportID' parameter and returned
  83  * in the 1st byte of the data.
  84  * The caller must pass a buffer of the size of the expected report in 'buffer'
  85  * including the report id byte, and initialize the variable pointed to by
  86  * 'len' to the total size of this buffer. Upon successful return, the report
  87  * (prefixed with the report-ID) is in 'buffer' and the actual length of the
  88  * report is returned in '*len'.
  89  * Returns: 0 on success, an error code otherwise.
  90  */
  91 int usbhidGetReport(USBDEVHANDLE usbh, int reportID, char *buffer, int *len);
  92
  93
  94 /**
  95  * Return description of error code
  96  * TODO? return error descr. of underlying libusb or hid layer too?
  97  */
  98 int usbhidStrerror_r( int err, char *buf, int len);
  99
 100 /* ------------------------------------------------------------------------ */
 101
 102 #endif /* __HIDUSB_H_INCLUDED__ */