SDRAngel  4.11.5
Developer docs for <a href="https://github.com/f4exb/sdrangel">SDRangel<\a>, an Open Source Qt5 / OpenGL 3.0+ SDR and signal analyzer frontend to various hardware.
Functions
hidapi API

Functions

int HID_API_EXPORT HID_API_CALL hid_init (void)
 Initialize the HIDAPI library. More...
 
int HID_API_EXPORT HID_API_CALL hid_exit (void)
 Finalize the HIDAPI library. More...
 
struct hid_device_info HID_API_EXPORT *HID_API_CALL hid_enumerate (unsigned short vendor_id, unsigned short product_id)
 Enumerate the HID Devices. More...
 
void HID_API_EXPORT HID_API_CALL hid_free_enumeration (struct hid_device_info *devs)
 Free an enumeration Linked List. More...
 
HID_API_EXPORT hid_device *HID_API_CALL hid_open (unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number)
 Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number. More...
 
HID_API_EXPORT hid_device *HID_API_CALL hid_open_path (const char *path)
 Open a HID device by its path name. More...
 
int HID_API_EXPORT HID_API_CALL hid_write (hid_device *device, const unsigned char *data, size_t length)
 Write an Output report to a HID device. More...
 
int HID_API_EXPORT HID_API_CALL hid_read_timeout (hid_device *dev, unsigned char *data, size_t length, int milliseconds)
 Read an Input report from a HID device with timeout. More...
 
int HID_API_EXPORT HID_API_CALL hid_read (hid_device *device, unsigned char *data, size_t length)
 Read an Input report from a HID device. More...
 
int HID_API_EXPORT HID_API_CALL hid_set_nonblocking (hid_device *device, int nonblock)
 Set the device handle to be non-blocking. More...
 
int HID_API_EXPORT HID_API_CALL hid_send_feature_report (hid_device *device, const unsigned char *data, size_t length)
 Send a Feature report to the device. More...
 
int HID_API_EXPORT HID_API_CALL hid_get_feature_report (hid_device *device, unsigned char *data, size_t length)
 Get a feature report from a HID device. More...
 
void HID_API_EXPORT HID_API_CALL hid_close (hid_device *device)
 Close a HID device. More...
 
int HID_API_EXPORT_CALL hid_get_manufacturer_string (hid_device *device, wchar_t *string, size_t maxlen)
 Get The Manufacturer String from a HID device. More...
 
int HID_API_EXPORT_CALL hid_get_product_string (hid_device *device, wchar_t *string, size_t maxlen)
 Get The Product String from a HID device. More...
 
int HID_API_EXPORT_CALL hid_get_serial_number_string (hid_device *device, wchar_t *string, size_t maxlen)
 Get The Serial Number String from a HID device. More...
 
int HID_API_EXPORT_CALL hid_get_indexed_string (hid_device *device, int string_index, wchar_t *string, size_t maxlen)
 Get a string from a HID device, based on its string index. More...
 
HID_API_EXPORT const wchar_t *HID_API_CALL hid_error (hid_device *device)
 Get a string describing the last error which occurred. More...
 

Detailed Description

Function Documentation

◆ hid_close()

void HID_API_EXPORT HID_API_CALL hid_close ( hid_device device)

Close a HID device.

Parameters
deviceA device handle returned from hid_open().

Definition at line 1157 of file hid-libusb.c.

References hid_device_::device_handle, hid_device_::input_reports, hid_device_::interface, hid_device_::mutex, hid_device_::shutdown_thread, hid_device_::thread, and hid_device_::transfer.

Referenced by fcdClose().

1158 {
1159  if (!dev)
1160  return;
1161 
1162  /* Cause read_thread() to stop. */
1163  dev->shutdown_thread = 1;
1164  libusb_cancel_transfer(dev->transfer);
1165 
1166  /* Wait for read_thread() to end. */
1167  pthread_join(dev->thread, NULL);
1168 
1169  /* Clean up the Transfer objects allocated in read_thread(). */
1170  free(dev->transfer->buffer);
1171  libusb_free_transfer(dev->transfer);
1172 
1173  /* release the interface */
1174  libusb_release_interface(dev->device_handle, dev->interface);
1175 
1176  /* Close the handle */
1177  libusb_close(dev->device_handle);
1178 
1179  /* Clear out the queue of received reports. */
1180  pthread_mutex_lock(&dev->mutex);
1181  while (dev->input_reports) {
1182  return_data(dev, NULL, 0);
1183  }
1184  pthread_mutex_unlock(&dev->mutex);
1185 
1186  free_hid_device(dev);
1187 }
+ Here is the caller graph for this function:

◆ hid_enumerate()

struct hid_device_info HID_API_EXPORT* HID_API_CALL hid_enumerate ( unsigned short  vendor_id,
unsigned short  product_id 
)

Enumerate the HID Devices.

This function returns a linked list of all the HID devices attached to the system which match vendor_id and product_id. If vendor_id is set to 0 then any vendor matches. If product_id is set to 0 then any product matches. If vendor_id and product_id are both set to 0, then all HID devices will be returned.

Parameters
vendor_idThe Vendor ID (VID) of the types of device to open.
product_idThe Product ID (PID) of the types of device to open.
Returns
This function returns a pointer to a linked list of type struct hid_device, containing information about the HID devices attached to the system, or NULL in the case of failure. Free this linked list by calling hid_free_enumeration().

Definition at line 444 of file hid-libusb.c.

References hid_init(), i, hid_device_info::next, and hid_device_info::path.

Referenced by FCDProPlugin::enumSampleSources(), FCDProPlusPlugin::enumSampleSources(), fcdOpen(), and hid_open().

445 {
446  libusb_device **devs;
447  libusb_device *dev;
448  libusb_device_handle *handle;
449  ssize_t num_devs;
450  int i = 0;
451 
452  struct hid_device_info *root = NULL; /* return object */
453  struct hid_device_info *cur_dev = NULL;
454 
455  if(hid_init() < 0)
456  return NULL;
457 
458  num_devs = libusb_get_device_list(usb_context, &devs);
459  if (num_devs < 0)
460  return NULL;
461  while ((dev = devs[i++]) != NULL) {
462  struct libusb_device_descriptor desc;
463  struct libusb_config_descriptor *conf_desc = NULL;
464  int j, k;
465  int interface_num = 0;
466 
467  int res = libusb_get_device_descriptor(dev, &desc);
468  unsigned short dev_vid = desc.idVendor;
469  unsigned short dev_pid = desc.idProduct;
470 
471  res = libusb_get_active_config_descriptor(dev, &conf_desc);
472  if (res < 0)
473  libusb_get_config_descriptor(dev, 0, &conf_desc);
474  if (conf_desc) {
475  for (j = 0; j < conf_desc->bNumInterfaces; j++) {
476  const struct libusb_interface *intf = &conf_desc->interface[j];
477  for (k = 0; k < intf->num_altsetting; k++) {
478  const struct libusb_interface_descriptor *intf_desc;
479  intf_desc = &intf->altsetting[k];
480  if (intf_desc->bInterfaceClass == LIBUSB_CLASS_HID) {
481  interface_num = intf_desc->bInterfaceNumber;
482 
483  /* Check the VID/PID against the arguments */
484  if ((vendor_id == 0x0 || vendor_id == dev_vid) &&
485  (product_id == 0x0 || product_id == dev_pid)) {
486  struct hid_device_info *tmp;
487 
488  /* VID/PID match. Create the record. */
489  tmp = calloc(1, sizeof(struct hid_device_info));
490  if (cur_dev) {
491  cur_dev->next = tmp;
492  }
493  else {
494  root = tmp;
495  }
496  cur_dev = tmp;
497 
498  /* Fill out the record */
499  cur_dev->next = NULL;
500  cur_dev->path = make_path(dev, interface_num);
501 
502  res = libusb_open(dev, &handle);
503 
504  if (res >= 0) {
505  /* Serial Number */
506  if (desc.iSerialNumber > 0)
507  cur_dev->serial_number =
508  get_usb_string(handle, desc.iSerialNumber);
509 
510  /* Manufacturer and Product strings */
511  if (desc.iManufacturer > 0)
512  cur_dev->manufacturer_string =
513  get_usb_string(handle, desc.iManufacturer);
514  if (desc.iProduct > 0)
515  cur_dev->product_string =
516  get_usb_string(handle, desc.iProduct);
517 
518 #ifdef INVASIVE_GET_USAGE
519 {
520  /*
521  This section is removed because it is too
522  invasive on the system. Getting a Usage Page
523  and Usage requires parsing the HID Report
524  descriptor. Getting a HID Report descriptor
525  involves claiming the interface. Claiming the
526  interface involves detaching the kernel driver.
527  Detaching the kernel driver is hard on the system
528  because it will unclaim interfaces (if another
529  app has them claimed) and the re-attachment of
530  the driver will sometimes change /dev entry names.
531  It is for these reasons that this section is
532  #if 0. For composite devices, use the interface
533  field in the hid_device_info struct to distinguish
534  between interfaces. */
535  unsigned char data[256];
536 #ifdef DETACH_KERNEL_DRIVER
537  int detached = 0;
538  /* Usage Page and Usage */
539  res = libusb_kernel_driver_active(handle, interface_num);
540  if (res == 1) {
541  res = libusb_detach_kernel_driver(handle, interface_num);
542  if (res < 0)
543  LOG("Couldn't detach kernel driver, even though a kernel driver was attached.");
544  else
545  detached = 1;
546  }
547 #endif
548  res = libusb_claim_interface(handle, interface_num);
549  if (res >= 0) {
550  /* Get the HID Report Descriptor. */
551  res = libusb_control_transfer(handle, LIBUSB_ENDPOINT_IN|LIBUSB_RECIPIENT_INTERFACE, LIBUSB_REQUEST_GET_DESCRIPTOR, (LIBUSB_DT_REPORT << 8)|interface_num, 0, data, sizeof(data), 5000);
552  if (res >= 0) {
553  unsigned short page=0, usage=0;
554  /* Parse the usage and usage page
555  out of the report descriptor. */
556  get_usage(data, res, &page, &usage);
557  cur_dev->usage_page = page;
558  cur_dev->usage = usage;
559  }
560  else
561  LOG("libusb_control_transfer() for getting the HID report failed with %d\n", res);
562 
563  /* Release the interface */
564  res = libusb_release_interface(handle, interface_num);
565  if (res < 0)
566  LOG("Can't release the interface.\n");
567  }
568  else
569  LOG("Can't claim interface %d\n", res);
570 #ifdef DETACH_KERNEL_DRIVER
571  /* Re-attach kernel driver if necessary. */
572  if (detached) {
573  res = libusb_attach_kernel_driver(handle, interface_num);
574  if (res < 0)
575  LOG("Couldn't re-attach kernel driver.\n");
576  }
577 #endif
578 }
579 #endif /* INVASIVE_GET_USAGE */
580 
581  libusb_close(handle);
582  }
583  /* VID/PID */
584  cur_dev->vendor_id = dev_vid;
585  cur_dev->product_id = dev_pid;
586 
587  /* Release Number */
588  cur_dev->release_number = desc.bcdDevice;
589 
590  /* Interface Number */
591  cur_dev->interface_number = interface_num;
592  }
593  }
594  } /* altsettings */
595  } /* interfaces */
596  libusb_free_config_descriptor(conf_desc);
597  }
598  }
599 
600  libusb_free_device_list(devs, 1);
601 
602  return root;
603 }
int interface_number
Definition: hidapi.h:75
wchar_t * manufacturer_string
Definition: hidapi.h:62
char * path
Definition: hidapi.h:51
struct hid_device_info * next
Definition: hidapi.h:78
unsigned short product_id
Definition: hidapi.h:55
wchar_t * serial_number
Definition: hidapi.h:57
#define LOG(...)
Definition: hid-libusb.c:61
int32_t i
Definition: decimators.h:244
unsigned short vendor_id
Definition: hidapi.h:53
wchar_t * product_string
Definition: hidapi.h:64
int HID_API_EXPORT hid_init(void)
Initialize the HIDAPI library.
Definition: hid-libusb.c:416
unsigned short usage
Definition: hidapi.h:70
unsigned short usage_page
Definition: hidapi.h:67
unsigned short release_number
Definition: hidapi.h:60
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ hid_error()

HID_API_EXPORT const wchar_t* HID_API_CALL hid_error ( hid_device device)

Get a string describing the last error which occurred.

Parameters
deviceA device handle returned from hid_open().
Returns
This function returns a string containing the last error which occurred or NULL if none has occurred.

Definition at line 1221 of file hid-libusb.c.

1222 {
1223  return NULL;
1224 }

◆ hid_exit()

int HID_API_EXPORT HID_API_CALL hid_exit ( void  )

Finalize the HIDAPI library.

This function frees all of the static data associated with HIDAPI. It should be called at the end of execution to avoid memory leaks.

Returns
This function returns 0 on success and -1 on error.

Definition at line 434 of file hid-libusb.c.

435 {
436  if (usb_context) {
437  libusb_exit(usb_context);
438  usb_context = NULL;
439  }
440 
441  return 0;
442 }

◆ hid_free_enumeration()

void HID_API_EXPORT HID_API_CALL hid_free_enumeration ( struct hid_device_info devs)

Free an enumeration Linked List.

This function frees a linked list created by hid_enumerate().

Parameters
devsPointer to a list of struct_device returned from hid_enumerate().

Definition at line 605 of file hid-libusb.c.

References hid_device_info::manufacturer_string, hid_device_info::next, input_report::next, hid_device_info::path, hid_device_info::product_string, and hid_device_info::serial_number.

Referenced by fcdOpen(), and hid_open().

606 {
607  struct hid_device_info *d = devs;
608  while (d) {
609  struct hid_device_info *next = d->next;
610  free(d->path);
611  free(d->serial_number);
612  free(d->manufacturer_string);
613  free(d->product_string);
614  free(d);
615  d = next;
616  }
617 }
wchar_t * manufacturer_string
Definition: hidapi.h:62
char * path
Definition: hidapi.h:51
struct hid_device_info * next
Definition: hidapi.h:78
wchar_t * serial_number
Definition: hidapi.h:57
wchar_t * product_string
Definition: hidapi.h:64
+ Here is the caller graph for this function:

◆ hid_get_feature_report()

int HID_API_EXPORT HID_API_CALL hid_get_feature_report ( hid_device device,
unsigned char *  data,
size_t  length 
)

Get a feature report from a HID device.

Make sure to set the first byte of data[] to the Report ID of the report to be read. Make sure to allow space for this extra byte in data[].

Parameters
deviceA device handle returned from hid_open().
dataA buffer to put the read data into, including the Report ID. Set the first byte of data[] to the Report ID of the report to be read.
lengthThe number of bytes to read, including an extra byte for the report ID. The buffer can be longer than the actual report.
Returns
This function returns the number of bytes read and -1 on error.

Definition at line 1126 of file hid-libusb.c.

References hid_device_::device_handle, and hid_device_::interface.

1127 {
1128  int res = -1;
1129  int skipped_report_id = 0;
1130  int report_number = data[0];
1131 
1132  if (report_number == 0x0) {
1133  /* Offset the return buffer by 1, so that the report ID
1134  will remain in byte 0. */
1135  data++;
1136  length--;
1137  skipped_report_id = 1;
1138  }
1139  res = libusb_control_transfer(dev->device_handle,
1140  LIBUSB_REQUEST_TYPE_CLASS|LIBUSB_RECIPIENT_INTERFACE|LIBUSB_ENDPOINT_IN,
1141  0x01/*HID get_report*/,
1142  (3/*HID feature*/ << 8) | report_number,
1143  dev->interface,
1144  (unsigned char *)data, length,
1145  1000/*timeout millis*/);
1146 
1147  if (res < 0)
1148  return -1;
1149 
1150  if (skipped_report_id)
1151  res++;
1152 
1153  return res;
1154 }

◆ hid_get_indexed_string()

int HID_API_EXPORT_CALL hid_get_indexed_string ( hid_device device,
int  string_index,
wchar_t *  string,
size_t  maxlen 
)

Get a string from a HID device, based on its string index.

Parameters
deviceA device handle returned from hid_open().
string_indexThe index of the string to get.
stringA wide string buffer to put the data into.
maxlenThe length of the buffer in multiples of wchar_t.
Returns
This function returns 0 on success and -1 on error.

Definition at line 1205 of file hid-libusb.c.

Referenced by hid_get_manufacturer_string(), hid_get_product_string(), and hid_get_serial_number_string().

1206 {
1207  wchar_t *str;
1208 
1209  str = get_usb_string(dev->device_handle, string_index);
1210  if (str) {
1211  wcsncpy(string, str, maxlen);
1212  string[maxlen-1] = L'\0';
1213  free(str);
1214  return 0;
1215  }
1216  else
1217  return -1;
1218 }
+ Here is the caller graph for this function:

◆ hid_get_manufacturer_string()

int HID_API_EXPORT_CALL hid_get_manufacturer_string ( hid_device device,
wchar_t *  string,
size_t  maxlen 
)

Get The Manufacturer String from a HID device.

Parameters
deviceA device handle returned from hid_open().
stringA wide string buffer to put the data into.
maxlenThe length of the buffer in multiples of wchar_t.
Returns
This function returns 0 on success and -1 on error.

Definition at line 1190 of file hid-libusb.c.

References hid_get_indexed_string(), and hid_device_::manufacturer_index.

1191 {
1192  return hid_get_indexed_string(dev, dev->manufacturer_index, string, maxlen);
1193 }
int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *dev, int string_index, wchar_t *string, size_t maxlen)
Get a string from a HID device, based on its string index.
Definition: hid-libusb.c:1205
+ Here is the call graph for this function:

◆ hid_get_product_string()

int HID_API_EXPORT_CALL hid_get_product_string ( hid_device device,
wchar_t *  string,
size_t  maxlen 
)

Get The Product String from a HID device.

Parameters
deviceA device handle returned from hid_open().
stringA wide string buffer to put the data into.
maxlenThe length of the buffer in multiples of wchar_t.
Returns
This function returns 0 on success and -1 on error.

Definition at line 1195 of file hid-libusb.c.

References hid_get_indexed_string(), and hid_device_::product_index.

1196 {
1197  return hid_get_indexed_string(dev, dev->product_index, string, maxlen);
1198 }
int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *dev, int string_index, wchar_t *string, size_t maxlen)
Get a string from a HID device, based on its string index.
Definition: hid-libusb.c:1205
+ Here is the call graph for this function:

◆ hid_get_serial_number_string()

int HID_API_EXPORT_CALL hid_get_serial_number_string ( hid_device device,
wchar_t *  string,
size_t  maxlen 
)

Get The Serial Number String from a HID device.

Parameters
deviceA device handle returned from hid_open().
stringA wide string buffer to put the data into.
maxlenThe length of the buffer in multiples of wchar_t.
Returns
This function returns 0 on success and -1 on error.

Definition at line 1200 of file hid-libusb.c.

References hid_get_indexed_string(), and hid_device_::serial_index.

1201 {
1202  return hid_get_indexed_string(dev, dev->serial_index, string, maxlen);
1203 }
int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *dev, int string_index, wchar_t *string, size_t maxlen)
Get a string from a HID device, based on its string index.
Definition: hid-libusb.c:1205
+ Here is the call graph for this function:

◆ hid_init()

int HID_API_EXPORT HID_API_CALL hid_init ( void  )

Initialize the HIDAPI library.

This function initializes the HIDAPI library. Calling it is not strictly necessary, as it will be called automatically by hid_enumerate() and any of the hid_open_*() functions if it is needed. This function should be called at the beginning of execution however, if there is a chance of HIDAPI handles being opened by different threads simultaneously.

Returns
This function returns 0 on success and -1 on error.

Definition at line 416 of file hid-libusb.c.

Referenced by hid_enumerate(), and hid_open_path().

417 {
418  if (!usb_context) {
419  const char *locale;
420 
421  /* Init Libusb */
422  if (libusb_init(&usb_context))
423  return -1;
424 
425  /* Set the locale if it's not set. */
426  locale = setlocale(LC_CTYPE, NULL);
427  if (!locale)
428  setlocale(LC_CTYPE, "");
429  }
430 
431  return 0;
432 }
+ Here is the caller graph for this function:

◆ hid_open()

HID_API_EXPORT hid_device* HID_API_CALL hid_open ( unsigned short  vendor_id,
unsigned short  product_id,
const wchar_t *  serial_number 
)

Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number.

If serial_number is NULL, the first device with the specified VID and PID is opened.

Parameters
vendor_idThe Vendor ID (VID) of the device to open.
product_idThe Product ID (PID) of the device to open.
serial_numberThe Serial Number of the device to open (Optionally NULL).
Returns
This function returns a pointer to a hid_device object on success or NULL on failure.

Definition at line 619 of file hid-libusb.c.

References hid_enumerate(), hid_free_enumeration(), hid_open_path(), hid_device_info::next, hid_device_info::path, hid_device_info::product_id, hid_device_info::serial_number, and hid_device_info::vendor_id.

620 {
621  struct hid_device_info *devs, *cur_dev;
622  const char *path_to_open = NULL;
623  hid_device *handle = NULL;
624 
626  cur_dev = devs;
627  while (cur_dev) {
628  if (cur_dev->vendor_id == vendor_id &&
629  cur_dev->product_id == product_id) {
630  if (serial_number) {
631  if (wcscmp(serial_number, cur_dev->serial_number) == 0) {
632  path_to_open = cur_dev->path;
633  break;
634  }
635  }
636  else {
637  path_to_open = cur_dev->path;
638  break;
639  }
640  }
641  cur_dev = cur_dev->next;
642  }
643 
644  if (path_to_open) {
645  /* Open the device */
646  handle = hid_open_path(path_to_open);
647  }
648 
649  hid_free_enumeration(devs);
650 
651  return handle;
652 }
char * path
Definition: hidapi.h:51
struct hid_device_info * next
Definition: hidapi.h:78
unsigned short product_id
Definition: hidapi.h:55
hid_device *HID_API_EXPORT hid_open_path(const char *path)
Open a HID device by its path name.
Definition: hid-libusb.c:792
wchar_t * serial_number
Definition: hidapi.h:57
unsigned short vendor_id
Definition: hidapi.h:53
struct hid_device_info HID_API_EXPORT * hid_enumerate(unsigned short vendor_id, unsigned short product_id)
Enumerate the HID Devices.
Definition: hid-libusb.c:444
void HID_API_EXPORT hid_free_enumeration(struct hid_device_info *devs)
Free an enumeration Linked List.
Definition: hid-libusb.c:605
+ Here is the call graph for this function:

◆ hid_open_path()

HID_API_EXPORT hid_device* HID_API_CALL hid_open_path ( const char *  path)

Open a HID device by its path name.

The path name be determined by calling hid_enumerate(), or a platform-specific path name can be used (eg: /dev/hidraw0 on Linux).

Parameters
pathThe path name of the device to open
Returns
This function returns a pointer to a hid_device object on success or NULL on failure.

Definition at line 792 of file hid-libusb.c.

References hid_init().

Referenced by fcdOpen(), and hid_open().

793 {
794  hid_device *dev = NULL;
795 
796  libusb_device **devs;
797  libusb_device *usb_dev;
798  int res;
799  int d = 0;
800  int good_open = 0;
801 
802  if(hid_init() < 0)
803  return NULL;
804 
805  dev = new_hid_device();
806 
807  libusb_get_device_list(usb_context, &devs);
808  while ((usb_dev = devs[d++]) != NULL) {
809  struct libusb_device_descriptor desc;
810  struct libusb_config_descriptor *conf_desc = NULL;
811  int i,j,k;
812  libusb_get_device_descriptor(usb_dev, &desc);
813 
814  if (libusb_get_active_config_descriptor(usb_dev, &conf_desc) < 0)
815  continue;
816  for (j = 0; j < conf_desc->bNumInterfaces; j++) {
817  const struct libusb_interface *intf = &conf_desc->interface[j];
818  for (k = 0; k < intf->num_altsetting; k++) {
819  const struct libusb_interface_descriptor *intf_desc;
820  intf_desc = &intf->altsetting[k];
821  if (intf_desc->bInterfaceClass == LIBUSB_CLASS_HID) {
822  char *dev_path = make_path(usb_dev, intf_desc->bInterfaceNumber);
823  if (!strcmp(dev_path, path)) {
824  /* Matched Paths. Open this device */
825 
826  /* OPEN HERE */
827  res = libusb_open(usb_dev, &dev->device_handle);
828  if (res < 0) {
829  LOG("can't open device\n");
830  free(dev_path);
831  break;
832  }
833  good_open = 1;
834 #ifdef DETACH_KERNEL_DRIVER
835  /* Detach the kernel driver, but only if the
836  device is managed by the kernel */
837  if (libusb_kernel_driver_active(dev->device_handle, intf_desc->bInterfaceNumber) == 1) {
838  res = libusb_detach_kernel_driver(dev->device_handle, intf_desc->bInterfaceNumber);
839  if (res < 0) {
840  libusb_close(dev->device_handle);
841  LOG("Unable to detach Kernel Driver\n");
842  free(dev_path);
843  good_open = 0;
844  break;
845  }
846  }
847 #endif
848  res = libusb_claim_interface(dev->device_handle, intf_desc->bInterfaceNumber);
849  if (res < 0) {
850  LOG("can't claim interface %d: %d\n", intf_desc->bInterfaceNumber, res);
851  free(dev_path);
852  libusb_close(dev->device_handle);
853  good_open = 0;
854  break;
855  }
856 
857  /* Store off the string descriptor indexes */
858  dev->manufacturer_index = desc.iManufacturer;
859  dev->product_index = desc.iProduct;
860  dev->serial_index = desc.iSerialNumber;
861 
862  /* Store off the interface number */
863  dev->interface = intf_desc->bInterfaceNumber;
864 
865  /* Find the INPUT and OUTPUT endpoints. An
866  OUTPUT endpoint is not required. */
867  for (i = 0; i < intf_desc->bNumEndpoints; i++) {
868  const struct libusb_endpoint_descriptor *ep
869  = &intf_desc->endpoint[i];
870 
871  /* Determine the type and direction of this
872  endpoint. */
873  int is_interrupt =
874  (ep->bmAttributes & LIBUSB_TRANSFER_TYPE_MASK)
875  == LIBUSB_TRANSFER_TYPE_INTERRUPT;
876  int is_output =
877  (ep->bEndpointAddress & LIBUSB_ENDPOINT_DIR_MASK)
878  == LIBUSB_ENDPOINT_OUT;
879  int is_input =
880  (ep->bEndpointAddress & LIBUSB_ENDPOINT_DIR_MASK)
881  == LIBUSB_ENDPOINT_IN;
882 
883  /* Decide whether to use it for intput or output. */
884  if (dev->input_endpoint == 0 &&
885  is_interrupt && is_input) {
886  /* Use this endpoint for INPUT */
887  dev->input_endpoint = ep->bEndpointAddress;
888  dev->input_ep_max_packet_size = ep->wMaxPacketSize;
889  }
890  if (dev->output_endpoint == 0 &&
891  is_interrupt && is_output) {
892  /* Use this endpoint for OUTPUT */
893  dev->output_endpoint = ep->bEndpointAddress;
894  }
895  }
896 
897  pthread_create(&dev->thread, NULL, read_thread, dev);
898 
899  /* Wait here for the read thread to be initialized. */
900  pthread_barrier_wait(&dev->barrier);
901 
902  }
903  free(dev_path);
904  }
905  }
906  }
907  libusb_free_config_descriptor(conf_desc);
908 
909  }
910 
911  libusb_free_device_list(devs, 1);
912 
913  /* If we have a good handle, return it. */
914  if (good_open) {
915  return dev;
916  }
917  else {
918  /* Unable to open any devices. */
919  free_hid_device(dev);
920  return NULL;
921  }
922 }
int product_index
Definition: hid-libusb.c:105
int serial_index
Definition: hid-libusb.c:106
int manufacturer_index
Definition: hid-libusb.c:104
libusb_device_handle * device_handle
Definition: hid-libusb.c:93
int input_ep_max_packet_size
Definition: hid-libusb.c:98
pthread_barrier_t barrier
Definition: hid-libusb.c:115
#define LOG(...)
Definition: hid-libusb.c:61
int32_t i
Definition: decimators.h:244
int HID_API_EXPORT hid_init(void)
Initialize the HIDAPI library.
Definition: hid-libusb.c:416
pthread_t thread
Definition: hid-libusb.c:112
int input_endpoint
Definition: hid-libusb.c:96
int output_endpoint
Definition: hid-libusb.c:97
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ hid_read()

int HID_API_EXPORT HID_API_CALL hid_read ( hid_device device,
unsigned char *  data,
size_t  length 
)

Read an Input report from a HID device.

Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report number if the device uses numbered reports.

Parameters
deviceA device handle returned from hid_open().
dataA buffer to put the read data into.
lengthThe number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number.
Returns
This function returns the actual number of bytes read and -1 on error. If no packet was available to be read and the handle is in non-blocking mode, this function returns 0.

Definition at line 1083 of file hid-libusb.c.

References hid_device_::blocking, and hid_read_timeout().

Referenced by fcdAppGetParam(), fcdAppSetFreq(), fcdAppSetFreqkHz(), fcdAppSetParam(), fcdBlErase(), fcdBlVerifyFirmware(), fcdBlWriteFirmware(), fcdGetCaps(), fcdGetCapsStr(), fcdGetFwVerStr(), and fcdGetMode().

1084 {
1085  return hid_read_timeout(dev, data, length, dev->blocking ? -1 : 0);
1086 }
int HID_API_EXPORT hid_read_timeout(hid_device *dev, unsigned char *data, size_t length, int milliseconds)
Read an Input report from a HID device with timeout.
Definition: hid-libusb.c:998
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ hid_read_timeout()

int HID_API_EXPORT HID_API_CALL hid_read_timeout ( hid_device dev,
unsigned char *  data,
size_t  length,
int  milliseconds 
)

Read an Input report from a HID device with timeout.

Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report number if the device uses numbered reports.

Parameters
deviceA device handle returned from hid_open().
dataA buffer to put the read data into.
lengthThe number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number.
millisecondstimeout in milliseconds or -1 for blocking wait.
Returns
This function returns the actual number of bytes read and -1 on error. If no packet was available to be read within the timeout period, this function returns 0.

Definition at line 998 of file hid-libusb.c.

References hid_device_::device_handle, hid_device_::input_endpoint, LOG, and hid_device_::mutex.

Referenced by hid_read().

999 {
1000  int bytes_read = -1;
1001 
1002 #if 0
1003  int transferred;
1004  int res = libusb_interrupt_transfer(dev->device_handle, dev->input_endpoint, data, length, &transferred, 5000);
1005  LOG("transferred: %d\n", transferred);
1006  return transferred;
1007 #endif
1008 
1009  pthread_mutex_lock(&dev->mutex);
1010  pthread_cleanup_push(&cleanup_mutex, dev);
1011 
1012  /* There's an input report queued up. Return it. */
1013  if (dev->input_reports) {
1014  /* Return the first one */
1015  bytes_read = return_data(dev, data, length);
1016  goto ret;
1017  }
1018 
1019  if (dev->shutdown_thread) {
1020  /* This means the device has been disconnected.
1021  An error code of -1 should be returned. */
1022  bytes_read = -1;
1023  goto ret;
1024  }
1025 
1026  if (milliseconds == -1) {
1027  /* Blocking */
1028  while (!dev->input_reports && !dev->shutdown_thread) {
1029  pthread_cond_wait(&dev->condition, &dev->mutex);
1030  }
1031  if (dev->input_reports) {
1032  bytes_read = return_data(dev, data, length);
1033  }
1034  }
1035  else if (milliseconds > 0) {
1036  /* Non-blocking, but called with timeout. */
1037  int res;
1038  struct timespec ts;
1039  clock_gettime(CLOCK_REALTIME, &ts);
1040  ts.tv_sec += milliseconds / 1000;
1041  ts.tv_nsec += (milliseconds % 1000) * 1000000;
1042  if (ts.tv_nsec >= 1000000000L) {
1043  ts.tv_sec++;
1044  ts.tv_nsec -= 1000000000L;
1045  }
1046 
1047  while (!dev->input_reports && !dev->shutdown_thread) {
1048  res = pthread_cond_timedwait(&dev->condition, &dev->mutex, &ts);
1049  if (res == 0) {
1050  if (dev->input_reports) {
1051  bytes_read = return_data(dev, data, length);
1052  break;
1053  }
1054 
1055  /* If we're here, there was a spurious wake up
1056  or the read thread was shutdown. Run the
1057  loop again (ie: don't break). */
1058  }
1059  else if (res == ETIMEDOUT) {
1060  /* Timed out. */
1061  bytes_read = 0;
1062  break;
1063  }
1064  else {
1065  /* Error. */
1066  bytes_read = -1;
1067  break;
1068  }
1069  }
1070  }
1071  else {
1072  /* Purely non-blocking */
1073  bytes_read = 0;
1074  }
1075 
1076 ret:
1077  pthread_mutex_unlock(&dev->mutex);
1078  pthread_cleanup_pop(0);
1079 
1080  return bytes_read;
1081 }
pthread_mutex_t mutex
Definition: hid-libusb.c:113
pthread_cond_t condition
Definition: hid-libusb.c:114
int shutdown_thread
Definition: hid-libusb.c:116
struct input_report * input_reports
Definition: hid-libusb.c:121
libusb_device_handle * device_handle
Definition: hid-libusb.c:93
#define LOG(...)
Definition: hid-libusb.c:61
int input_endpoint
Definition: hid-libusb.c:96
+ Here is the caller graph for this function:

◆ hid_send_feature_report()

int HID_API_EXPORT HID_API_CALL hid_send_feature_report ( hid_device device,
const unsigned char *  data,
size_t  length 
)

Send a Feature report to the device.

Feature reports are sent over the Control endpoint as a Set_Report transfer. The first byte of data[] must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to hid_send_feature_report() will always contain one more byte than the report contains. For example, if a hid report is 16 bytes long, 17 bytes must be passed to hid_send_feature_report(): the Report ID (or 0x0, for devices which do not use numbered reports), followed by the report data (16 bytes). In this example, the length passed in would be 17.

Parameters
deviceA device handle returned from hid_open().
dataThe data to send, including the report number as the first byte.
lengthThe length in bytes of the data to send, including the report number.
Returns
This function returns the actual number of bytes written and -1 on error.

Definition at line 1096 of file hid-libusb.c.

References hid_device_::device_handle, and hid_device_::interface.

1097 {
1098  int res = -1;
1099  int skipped_report_id = 0;
1100  int report_number = data[0];
1101 
1102  if (report_number == 0x0) {
1103  data++;
1104  length--;
1105  skipped_report_id = 1;
1106  }
1107 
1108  res = libusb_control_transfer(dev->device_handle,
1109  LIBUSB_REQUEST_TYPE_CLASS|LIBUSB_RECIPIENT_INTERFACE|LIBUSB_ENDPOINT_OUT,
1110  0x09/*HID set_report*/,
1111  (3/*HID feature*/ << 8) | report_number,
1112  dev->interface,
1113  (unsigned char *)data, length,
1114  1000/*timeout millis*/);
1115 
1116  if (res < 0)
1117  return -1;
1118 
1119  /* Account for the report ID */
1120  if (skipped_report_id)
1121  length++;
1122 
1123  return length;
1124 }

◆ hid_set_nonblocking()

int HID_API_EXPORT HID_API_CALL hid_set_nonblocking ( hid_device device,
int  nonblock 
)

Set the device handle to be non-blocking.

In non-blocking mode calls to hid_read() will return immediately with a value of 0 if there is no data to be read. In blocking mode, hid_read() will wait (block) until there is data to read before returning.

Nonblocking can be turned on and off at any time.

Parameters
deviceA device handle returned from hid_open().
nonblockenable or not the nonblocking reads
  • 1 to enable nonblocking
  • 0 to disable nonblocking.
Returns
This function returns 0 on success and -1 on error.

Definition at line 1088 of file hid-libusb.c.

References hid_device_::blocking.

1089 {
1090  dev->blocking = !nonblock;
1091 
1092  return 0;
1093 }

◆ hid_write()

int HID_API_EXPORT HID_API_CALL hid_write ( hid_device device,
const unsigned char *  data,
size_t  length 
)

Write an Output report to a HID device.

The first byte of data[] must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to hid_write() will always contain one more byte than the report contains. For example, if a hid report is 16 bytes long, 17 bytes must be passed to hid_write(), the Report ID (or 0x0, for devices with a single report), followed by the report data (16 bytes). In this example, the length passed in would be 17.

hid_write() will send the data on the first OUT endpoint, if one exists. If it does not, it will send the data through the Control Endpoint (Endpoint 0).

Parameters
deviceA device handle returned from hid_open().
dataThe data to send, including the report number as the first byte.
lengthThe length in bytes of the data to send.
Returns
This function returns the actual number of bytes written and -1 on error.

Definition at line 925 of file hid-libusb.c.

References hid_device_::device_handle, hid_device_::interface, and hid_device_::output_endpoint.

Referenced by fcdAppGetParam(), fcdAppReset(), fcdAppSetFreq(), fcdAppSetFreqkHz(), fcdAppSetParam(), fcdBlErase(), fcdBlReset(), fcdBlVerifyFirmware(), fcdBlWriteFirmware(), fcdGetCaps(), fcdGetCapsStr(), fcdGetFwVerStr(), and fcdGetMode().

926 {
927  int res;
928  int report_number = data[0];
929  int skipped_report_id = 0;
930 
931  if (report_number == 0x0) {
932  data++;
933  length--;
934  skipped_report_id = 1;
935  }
936 
937 
938  if (dev->output_endpoint <= 0) {
939  /* No interrput out endpoint. Use the Control Endpoint */
940  res = libusb_control_transfer(dev->device_handle,
941  LIBUSB_REQUEST_TYPE_CLASS|LIBUSB_RECIPIENT_INTERFACE|LIBUSB_ENDPOINT_OUT,
942  0x09/*HID Set_Report*/,
943  (2/*HID output*/ << 8) | report_number,
944  dev->interface,
945  (unsigned char *)data, length,
946  1000/*timeout millis*/);
947 
948  if (res < 0)
949  return -1;
950 
951  if (skipped_report_id)
952  length++;
953 
954  return length;
955  }
956  else {
957  /* Use the interrupt out endpoint */
958  int actual_length;
959  res = libusb_interrupt_transfer(dev->device_handle,
960  dev->output_endpoint,
961  (unsigned char*)data,
962  length,
963  &actual_length, 1000);
964 
965  if (res < 0)
966  return -1;
967 
968  if (skipped_report_id)
969  actual_length++;
970 
971  return actual_length;
972  }
973 }
+ Here is the caller graph for this function: