Skip to content

hid_error improvements #428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Youw merged 13 commits into from
Jun 21, 2022
Merged

hid_error improvements #428

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
bc8b8e3
fix: make the behaviour of methods which set hid_error more consistent
Julusian Jun 11, 2022
280e483
Fix hid_error documentation and hidraw implementation.
Youw Jun 12, 2022
ddeee39
hidraw hid_error improvements
Youw Jun 12, 2022
20ce7b0
Update hid.c
Youw Jun 12, 2022
3f8c087
fix build
Youw Jun 12, 2022
aa3c9b5
fix build
Youw Jun 12, 2022
e0106c5
fix build
Youw Jun 12, 2022
058992e
prefer reset error before, not after
Youw Jun 12, 2022
6b28781
more hidraw improvements
Youw Jun 12, 2022
f9fcc16
windows: add global error implementation
Youw Jun 12, 2022
537e658
fix build
Youw Jun 12, 2022
5bbf92f
fix build
Youw Jun 12, 2022
f82b8a8
fix build
Youw Jun 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 58 additions & 38 deletions hidapi/hidapi.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,7 @@ extern "C" {

@returns
This function returns 0 on success and -1 on error.
Call hid_error(NULL) to get the failure reason.
*/
int HID_API_EXPORT HID_API_CALL hid_init(void);

Expand All @@ -162,7 +163,7 @@ extern "C" {

@ingroup API

@returns
@returns
This function returns 0 on success and -1 on error.
*/
int HID_API_EXPORT HID_API_CALL hid_exit(void);
Expand All @@ -182,21 +183,25 @@ extern "C" {
@param product_id The 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_info, 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().
@returns
This function returns a pointer to a linked list of type
struct #hid_device_info, containing information about the HID devices
attached to the system,
or NULL in the case of failure or if no HID devices present in the system.
Call hid_error(NULL) to get the failure reason.

@note The returned value by this function must to be freed by calling hid_free_enumeration(),
when not needed anymore.
*/
struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_enumerate(unsigned short vendor_id, unsigned short product_id);

/** @brief Free an enumeration Linked List

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

@ingroup API
@param devs Pointer to a list of struct_device returned from
hid_enumerate().
@param devs Pointer to a list of struct_device returned from
hid_enumerate().
*/
void HID_API_EXPORT HID_API_CALL hid_free_enumeration(struct hid_device_info *devs);

Expand All @@ -206,17 +211,19 @@ extern "C" {
If @p serial_number is NULL, the first device with the
specified VID and PID is opened.

This function sets the return value of hid_error().

@ingroup API
@param vendor_id The Vendor ID (VID) of the device to open.
@param product_id The Product ID (PID) of the device to open.
@param serial_number The Serial Number of the device to open
(Optionally NULL).
(Optionally NULL).

@returns
This function returns a pointer to a #hid_device object on
success or NULL on failure.
Call hid_error(NULL) to get the failure reason.

@note The returned object must be freed by calling hid_close(),
when not needed anymore.
*/
HID_API_EXPORT hid_device * HID_API_CALL hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number);

Expand All @@ -226,14 +233,16 @@ extern "C" {
platform-specific path name can be used (eg: /dev/hidraw0 on
Linux).

This function sets the return value of hid_error().

@ingroup API
@param path The path name of the device to open
@param path The path name of the device to open

@returns
This function returns a pointer to a #hid_device object on
success or NULL on failure.
Call hid_error(NULL) to get the failure reason.

@note The returned object must be freed by calling hid_close(),
when not needed anymore.
*/
HID_API_EXPORT hid_device * HID_API_CALL hid_open_path(const char *path);

Expand All @@ -253,8 +262,6 @@ extern "C" {
one exists. If it does not, it will send the data through
the Control Endpoint (Endpoint 0).

This function sets the return value of hid_error().

@ingroup API
@param dev A device handle returned from hid_open().
@param data The data to send, including the report number as
Expand All @@ -264,6 +271,7 @@ extern "C" {
@returns
This function returns the actual number of bytes written and
-1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT HID_API_CALL hid_write(hid_device *dev, const unsigned char *data, size_t length);

Expand All @@ -273,8 +281,6 @@ extern "C" {
to the host through the INTERRUPT IN endpoint. The first byte will
contain the Report number if the device uses numbered reports.

This function sets the return value of hid_error().

@ingroup API
@param dev A device handle returned from hid_open().
@param data A buffer to put the read data into.
Expand All @@ -285,19 +291,19 @@ extern "C" {

@returns
This function returns the actual number of bytes read and
-1 on error. If no packet was available to be read within
-1 on error.
Call hid_error(dev) to get the failure reason.
If no packet was available to be read within
the timeout period, this function returns 0.
*/
int HID_API_EXPORT HID_API_CALL hid_read_timeout(hid_device *dev, unsigned char *data, size_t length, int milliseconds);

/** @brief Read an Input report from a HID device.

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

This function sets the return value of hid_error().

@ingroup API
@param dev A device handle returned from hid_open().
@param data A buffer to put the read data into.
Expand All @@ -307,7 +313,9 @@ extern "C" {

@returns
This function returns the actual number of bytes read and
-1 on error. If no packet was available to be read and
-1 on error.
Call hid_error(dev) to get the failure reason.
If no packet was available to be read and
the handle is in non-blocking mode, this function returns 0.
*/
int HID_API_EXPORT HID_API_CALL hid_read(hid_device *dev, unsigned char *data, size_t length);
Expand All @@ -329,6 +337,7 @@ extern "C" {

@returns
This function returns 0 on success and -1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT HID_API_CALL hid_set_nonblocking(hid_device *dev, int nonblock);

Expand All @@ -347,8 +356,6 @@ extern "C" {
report data (16 bytes). In this example, the length passed
in would be 17.

This function sets the return value of hid_error().

@ingroup API
@param dev A device handle returned from hid_open().
@param data The data to send, including the report number as
Expand All @@ -359,6 +366,7 @@ extern "C" {
@returns
This function returns the actual number of bytes written and
-1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT HID_API_CALL hid_send_feature_report(hid_device *dev, const unsigned char *data, size_t length);

Expand All @@ -370,8 +378,6 @@ extern "C" {
still contain the Report ID, and the report data will
start in data[1].

This function sets the return value of hid_error().

@ingroup API
@param dev A device handle returned from hid_open().
@param data A buffer to put the read data into, including
Expand All @@ -386,6 +392,7 @@ extern "C" {
This function returns the number of bytes read plus
one for the report ID (which is still in the first
byte), or -1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT HID_API_CALL hid_get_feature_report(hid_device *dev, unsigned char *data, size_t length);

Expand Down Expand Up @@ -413,13 +420,12 @@ extern "C" {
This function returns the number of bytes read plus
one for the report ID (which is still in the first
byte), or -1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT HID_API_CALL hid_get_input_report(hid_device *dev, unsigned char *data, size_t length);

/** @brief Close a HID device.

This function sets the return value of hid_error().

@ingroup API
@param dev A device handle returned from hid_open().
*/
Expand All @@ -434,6 +440,7 @@ extern "C" {

@returns
This function returns 0 on success and -1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT_CALL hid_get_manufacturer_string(hid_device *dev, wchar_t *string, size_t maxlen);

Expand All @@ -446,6 +453,7 @@ extern "C" {

@returns
This function returns 0 on success and -1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT_CALL hid_get_product_string(hid_device *dev, wchar_t *string, size_t maxlen);

Expand All @@ -458,6 +466,7 @@ extern "C" {

@returns
This function returns 0 on success and -1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT_CALL hid_get_serial_number_string(hid_device *dev, wchar_t *string, size_t maxlen);

Expand All @@ -471,32 +480,41 @@ extern "C" {

@returns
This function returns 0 on success and -1 on error.
Call hid_error(dev) to get the failure reason.
*/
int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *dev, int string_index, wchar_t *string, size_t maxlen);

/** @brief Get a string describing the last error which occurred.

Whether a function sets the last error is noted in its
documentation. These functions will reset the last error
to NULL before their execution.
This function is intended for logging/debugging purposes.

This function guarantees to never return NULL.
If there was no error in the last function call -
the returned string clearly indicates that.

Strings returned from hid_error() must not be freed by the user!
Any HIDAPI function that can explicitly indicate an execution failure
(e.g. by an error code, or by returning NULL) - may set the error string,
to be returned by this function.

This function is thread-safe, and error messages are thread-local.
Strings returned from hid_error() must not be freed by the user,
i.e. owned by HIDAPI library.
Device-specific error string may remain allocated at most until hid_close() is called.
Global error string may remain allocated at most until hid_exit() is called.

@ingroup API
@param dev A device handle returned from hid_open(),
or NULL to get the last non-device-specific error
(e.g. for errors in hid_open() itself).
(e.g. for errors in hid_open() or hid_enumerate()).

@returns
This function returns a string containing the last error
which occurred or NULL if none has occurred.
A string describing the last error (if any).
*/
HID_API_EXPORT const wchar_t* HID_API_CALL hid_error(hid_device *dev);

/** @brief Get a runtime version of the library.

This function is thread-safe.

@ingroup API

@returns
Expand All @@ -507,6 +525,8 @@ extern "C" {

/** @brief Get a runtime version string of the library.

This function is thread-safe.

@ingroup API

@returns
Expand Down
Loading