libs/hidapi/hidapi/hidapi.h

   1 /*******************************************************
   2  HIDAPI - Multi-Platform library for
   3  communication with HID devices.
   4
   5  Alan Ott
   6  Signal 11 Software
   7
   8  8/22/2009
   9
  10  Copyright 2009, All Rights Reserved.
  11
  12  At the discretion of the user of this library,
  13  this software may be licensed under the terms of the
  14  GNU General Public License v3, a BSD-Style license, or the
  15  original HIDAPI license as outlined in the LICENSE.txt,
  16  LICENSE-gpl3.txt, LICENSE-bsd.txt, and LICENSE-orig.txt
  17  files located at the root of the source distribution.
  18  These files may also be found in the public source
  19  code repository located at:
  20         http://github.com/signal11/hidapi .
  21 ********************************************************/
  22
  23 /** @file
  24  * @defgroup API hidapi API
  25  */
  26
  27 #ifndef HIDAPI_H__
  28 #define HIDAPI_H__
  29
  30 #include <wchar.h>
  31
  32 #if 0 // XXX we compile hidapi as static library
  33       #define HID_API_EXPORT __declspec(dllexport)
  34       #define HID_API_CALL
  35 #else
  36       #define HID_API_EXPORT /**< API export macro */
  37       #define HID_API_CALL /**< API call macro */
  38 #endif
  39
  40 #define HID_API_EXPORT_CALL HID_API_EXPORT HID_API_CALL /**< API export and call macro*/
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45                 struct hid_device_;
  46                 typedef struct hid_device_ hid_device; /**< opaque hidapi structure */
  47
  48                 /** hidapi info structure */
  49                 struct hid_device_info {
  50                         /** Platform-specific device path */
  51                         char *path;
  52                         /** Device Vendor ID */
  53                         unsigned short vendor_id;
  54                         /** Device Product ID */
  55                         unsigned short product_id;
  56                         /** Serial Number */
  57                         wchar_t *serial_number;
  58                         /** Device Release Number in binary-coded decimal,
  59                             also known as Device Version Number */
  60                         unsigned short release_number;
  61                         /** Manufacturer String */
  62                         wchar_t *manufacturer_string;
  63                         /** Product string */
  64                         wchar_t *product_string;
  65                         /** Usage Page for this Device/Interface
  66                             (Windows/Mac only). */
  67                         unsigned short usage_page;
  68                         /** Usage for this Device/Interface
  69                             (Windows/Mac only).*/
  70                         unsigned short usage;
  71                         /** The USB interface which this logical device
  72                             represents. Valid on both Linux implementations
  73                             in all cases, and valid on the Windows implementation
  74                             only if the device contains more than one interface. */
  75                         int interface_number;
  76
  77                         /** Pointer to the next device */
  78                         struct hid_device_info *next;
  79                 };
  80
  81
  82                 /** @brief Initialize the HIDAPI library.
  83
  84                         This function initializes the HIDAPI library. Calling it is not
  85                         strictly necessary, as it will be called automatically by
  86                         hid_enumerate() and any of the hid_open_*() functions if it is
  87                         needed.  This function should be called at the beginning of
  88                         execution however, if there is a chance of HIDAPI handles
  89                         being opened by different threads simultaneously.
  90
  91                         @ingroup API
  92
  93                         @returns
  94                                 This function returns 0 on success and -1 on error.
  95                 */
  96                 int HID_API_EXPORT HID_API_CALL hid_init(void);
  97
  98                 /** @brief Finalize the HIDAPI library.
  99
 100                         This function frees all of the static data associated with
 101                         HIDAPI. It should be called at the end of execution to avoid
 102                         memory leaks.
 103
 104                         @ingroup API
 105
 106                     @returns
 107                                 This function returns 0 on success and -1 on error.
 108                 */
 109                 int HID_API_EXPORT HID_API_CALL hid_exit(void);
 110
 111                 /** @brief Enumerate the HID Devices.
 112
 113                         This function returns a linked list of all the HID devices
 114                         attached to the system which match vendor_id and product_id.
 115                         If @p vendor_id is set to 0 then any vendor matches.
 116                         If @p product_id is set to 0 then any product matches.
 117                         If @p vendor_id and @p product_id are both set to 0, then
 118                         all HID devices will be returned.
 119
 120                         @ingroup API
 121                         @param vendor_id The Vendor ID (VID) of the types of device
 122                                 to open.
 123                         @param product_id The Product ID (PID) of the types of
 124                                 device to open.
 125
 126                     @returns
 127                         This function returns a pointer to a linked list of type
 128                         struct #hid_device, containing information about the HID devices
 129                         attached to the system, or NULL in the case of failure. Free
 130                         this linked list by calling hid_free_enumeration().
 131                 */
 132                 struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_enumerate(unsigned short vendor_id, unsigned short product_id);
 133
 134                 /** @brief Free an enumeration Linked List
 135
 136                     This function frees a linked list created by hid_enumerate().
 137
 138                         @ingroup API
 139                     @param devs Pointer to a list of struct_device returned from
 140                               hid_enumerate().
 141                 */
 142                 void  HID_API_EXPORT HID_API_CALL hid_free_enumeration(struct hid_device_info *devs);
 143
 144                 /** @brief Open a HID device using a Vendor ID (VID), Product ID
 145                         (PID) and optionally a serial number.
 146
 147                         If @p serial_number is NULL, the first device with the
 148                         specified VID and PID is opened.
 149
 150                         @ingroup API
 151                         @param vendor_id The Vendor ID (VID) of the device to open.
 152                         @param product_id The Product ID (PID) of the device to open.
 153                         @param serial_number The Serial Number of the device to open
 154                                                (Optionally NULL).
 155
 156                         @returns
 157                                 This function returns a pointer to a #hid_device object on
 158                                 success or NULL on failure.
 159                 */
 160                 HID_API_EXPORT hid_device * HID_API_CALL hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number);
 161
 162                 /** @brief Open a HID device by its path name.
 163
 164                         The path name be determined by calling hid_enumerate(), or a
 165                         platform-specific path name can be used (eg: /dev/hidraw0 on
 166                         Linux).
 167
 168                         @ingroup API
 169                     @param path The path name of the device to open
 170
 171                         @returns
 172                                 This function returns a pointer to a #hid_device object on
 173                                 success or NULL on failure.
 174                 */
 175                 HID_API_EXPORT hid_device * HID_API_CALL hid_open_path(const char *path);
 176
 177                 /** @brief Write an Output report to a HID device.
 178
 179                         The first byte of @p data[] must contain the Report ID. For
 180                         devices which only support a single report, this must be set
 181                         to 0x0. The remaining bytes contain the report data. Since
 182                         the Report ID is mandatory, calls to hid_write() will always
 183                         contain one more byte than the report contains. For example,
 184                         if a hid report is 16 bytes long, 17 bytes must be passed to
 185                         hid_write(), the Report ID (or 0x0, for devices with a
 186                         single report), followed by the report data (16 bytes). In
 187                         this example, the length passed in would be 17.
 188
 189                         hid_write() will send the data on the first OUT endpoint, if
 190                         one exists. If it does not, it will send the data through
 191                         the Control Endpoint (Endpoint 0).
 192
 193                         @ingroup API
 194                         @param device A device handle returned from hid_open().
 195                         @param data The data to send, including the report number as
 196                                 the first byte.
 197                         @param length The length in bytes of the data to send.
 198
 199                         @returns
 200                                 This function returns the actual number of bytes written and
 201                                 -1 on error.
 202                 */
 203                 int  HID_API_EXPORT HID_API_CALL hid_write(hid_device *device, const unsigned char *data, size_t length);
 204
 205                 /** @brief Read an Input report from a HID device with timeout.
 206
 207                         Input reports are returned
 208                         to the host through the INTERRUPT IN endpoint. The first byte will
 209                         contain the Report number if the device uses numbered reports.
 210
 211                         @ingroup API
 212                         @param device A device handle returned from hid_open().
 213                         @param data A buffer to put the read data into.
 214                         @param length The number of bytes to read. For devices with
 215                                 multiple reports, make sure to read an extra byte for
 216                                 the report number.
 217                         @param milliseconds timeout in milliseconds or -1 for blocking wait.
 218
 219                         @returns
 220                                 This function returns the actual number of bytes read and
 221                                 -1 on error. If no packet was available to be read within
 222                                 the timeout period, this function returns 0.
 223                 */
 224                 int HID_API_EXPORT HID_API_CALL hid_read_timeout(hid_device *dev, unsigned char *data, size_t length, int milliseconds);
 225
 226                 /** @brief Read an Input report from a HID device.
 227
 228                         Input reports are returned
 229                     to the host through the INTERRUPT IN endpoint. The first byte will
 230                         contain the Report number if the device uses numbered reports.
 231
 232                         @ingroup API
 233                         @param device A device handle returned from hid_open().
 234                         @param data A buffer to put the read data into.
 235                         @param length The number of bytes to read. For devices with
 236                                 multiple reports, make sure to read an extra byte for
 237                                 the report number.
 238
 239                         @returns
 240                                 This function returns the actual number of bytes read and
 241                                 -1 on error. If no packet was available to be read and
 242                                 the handle is in non-blocking mode, this function returns 0.
 243                 */
 244                 int  HID_API_EXPORT HID_API_CALL hid_read(hid_device *device, unsigned char *data, size_t length);
 245
 246                 /** @brief Set the device handle to be non-blocking.
 247
 248                         In non-blocking mode calls to hid_read() will return
 249                         immediately with a value of 0 if there is no data to be
 250                         read. In blocking mode, hid_read() will wait (block) until
 251                         there is data to read before returning.
 252
 253                         Nonblocking can be turned on and off at any time.
 254
 255                         @ingroup API
 256                         @param device A device handle returned from hid_open().
 257                         @param nonblock enable or not the nonblocking reads
 258                          - 1 to enable nonblocking
 259                          - 0 to disable nonblocking.
 260
 261                         @returns
 262                                 This function returns 0 on success and -1 on error.
 263                 */
 264                 int  HID_API_EXPORT HID_API_CALL hid_set_nonblocking(hid_device *device, int nonblock);
 265
 266                 /** @brief Send a Feature report to the device.
 267
 268                         Feature reports are sent over the Control endpoint as a
 269                         Set_Report transfer.  The first byte of @p data[] must
 270                         contain the Report ID. For devices which only support a
 271                         single report, this must be set to 0x0. The remaining bytes
 272                         contain the report data. Since the Report ID is mandatory,
 273                         calls to hid_send_feature_report() will always contain one
 274                         more byte than the report contains. For example, if a hid
 275                         report is 16 bytes long, 17 bytes must be passed to
 276                         hid_send_feature_report(): the Report ID (or 0x0, for
 277                         devices which do not use numbered reports), followed by the
 278                         report data (16 bytes). In this example, the length passed
 279                         in would be 17.
 280
 281                         @ingroup API
 282                         @param device A device handle returned from hid_open().
 283                         @param data The data to send, including the report number as
 284                                 the first byte.
 285                         @param length The length in bytes of the data to send, including
 286                                 the report number.
 287
 288                         @returns
 289                                 This function returns the actual number of bytes written and
 290                                 -1 on error.
 291                 */
 292                 int HID_API_EXPORT HID_API_CALL hid_send_feature_report(hid_device *device, const unsigned char *data, size_t length);
 293
 294                 /** @brief Get a feature report from a HID device.
 295
 296                         Set the first byte of @p data[] to the Report ID of the
 297                         report to be read.  Make sure to allow space for this
 298                         extra byte in @p data[]. Upon return, the first byte will
 299                         still contain the Report ID, and the report data will
 300                         start in data[1].
 301
 302                         @ingroup API
 303                         @param device A device handle returned from hid_open().
 304                         @param data A buffer to put the read data into, including
 305                                 the Report ID. Set the first byte of @p data[] to the
 306                                 Report ID of the report to be read, or set it to zero
 307                                 if your device does not use numbered reports.
 308                         @param length The number of bytes to read, including an
 309                                 extra byte for the report ID. The buffer can be longer
 310                                 than the actual report.
 311
 312                         @returns
 313                                 This function returns the number of bytes read plus
 314                                 one for the report ID (which is still in the first
 315                                 byte), or -1 on error.
 316                 */
 317                 int HID_API_EXPORT HID_API_CALL hid_get_feature_report(hid_device *device, unsigned char *data, size_t length);
 318
 319                 /** @brief Close a HID device.
 320
 321                         @ingroup API
 322                         @param device A device handle returned from hid_open().
 323                 */
 324                 void HID_API_EXPORT HID_API_CALL hid_close(hid_device *device);
 325
 326                 /** @brief Get The Manufacturer String from a HID device.
 327
 328                         @ingroup API
 329                         @param device A device handle returned from hid_open().
 330                         @param string A wide string buffer to put the data into.
 331                         @param maxlen The length of the buffer in multiples of wchar_t.
 332
 333                         @returns
 334                                 This function returns 0 on success and -1 on error.
 335                 */
 336                 int HID_API_EXPORT_CALL hid_get_manufacturer_string(hid_device *device, wchar_t *string, size_t maxlen);
 337
 338                 /** @brief Get The Product String from a HID device.
 339
 340                         @ingroup API
 341                         @param device A device handle returned from hid_open().
 342                         @param string A wide string buffer to put the data into.
 343                         @param maxlen The length of the buffer in multiples of wchar_t.
 344
 345                         @returns
 346                                 This function returns 0 on success and -1 on error.
 347                 */
 348                 int HID_API_EXPORT_CALL hid_get_product_string(hid_device *device, wchar_t *string, size_t maxlen);
 349
 350                 /** @brief Get The Serial Number String from a HID device.
 351
 352                         @ingroup API
 353                         @param device A device handle returned from hid_open().
 354                         @param string A wide string buffer to put the data into.
 355                         @param maxlen The length of the buffer in multiples of wchar_t.
 356
 357                         @returns
 358                                 This function returns 0 on success and -1 on error.
 359                 */
 360                 int HID_API_EXPORT_CALL hid_get_serial_number_string(hid_device *device, wchar_t *string, size_t maxlen);
 361
 362                 /** @brief Get a string from a HID device, based on its string index.
 363
 364                         @ingroup API
 365                         @param device A device handle returned from hid_open().
 366                         @param string_index The index of the string to get.
 367                         @param string A wide string buffer to put the data into.
 368                         @param maxlen The length of the buffer in multiples of wchar_t.
 369
 370                         @returns
 371                                 This function returns 0 on success and -1 on error.
 372                 */
 373                 int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *device, int string_index, wchar_t *string, size_t maxlen);
 374
 375                 /** @brief Get a string describing the last error which occurred.
 376
 377                         @ingroup API
 378                         @param device A device handle returned from hid_open().
 379
 380                         @returns
 381                                 This function returns a string containing the last error
 382                                 which occurred or NULL if none has occurred.
 383                 */
 384                 HID_API_EXPORT const wchar_t* HID_API_CALL hid_error(hid_device *device);
 385
 386 #ifdef __cplusplus
 387 }
 388 #endif
 389
 390 #endif
 391