From b9a937051ebbf2cc10d7612da4646711039c9c9d Mon Sep 17 00:00:00 2001 From: Daniel Pavel Date: Sun, 23 Sep 2012 17:21:20 +0300 Subject: [PATCH] documentation updates on hidapi --- logitech/hidapi.py | 60 ++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/logitech/hidapi.py b/logitech/hidapi.py index 283fb146..bd218727 100644 --- a/logitech/hidapi.py +++ b/logitech/hidapi.py @@ -18,14 +18,16 @@ __version__ = '0.2-hidapi-0.7.0' import os.path from collections import namedtuple -from ctypes import ( - cdll, create_string_buffer, create_unicode_buffer, - c_int, c_ushort, c_size_t, - c_char_p, c_wchar_p, c_void_p, - POINTER, Structure -) +from ctypes import (cdll, create_string_buffer, create_unicode_buffer, + c_int, c_ushort, c_size_t, + c_char_p, c_wchar_p, c_void_p, + POINTER, Structure) +# +# look for a native implementation in the same directory as this file +# + _api = None native_path = os.path.dirname(__file__) for native_implementation in ('hidraw', 'libusb'): @@ -56,7 +58,7 @@ _DeviceInfo._fields_ = [ ('usage_page', c_ushort), ('usage', c_ushort), ('interface', c_int), - ('next', POINTER(_DeviceInfo)) + ('next_device', POINTER(_DeviceInfo)) ] @@ -153,14 +155,13 @@ _api.hid_error.restype = c_wchar_p def init(): """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 + This function initializes the HIDAPI library. Calling it is not strictly + necessary, as it will be called automatically by enumerate() and any of the + 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: True if successful. + :returns: ``True`` if successful. """ return _api.hid_init() == 0 @@ -168,11 +169,10 @@ def init(): def exit(): """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. + 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: True if successful. + :returns: ``True`` if successful. """ return _api.hid_exit() == 0 @@ -183,7 +183,7 @@ def enumerate(vendor_id=None, product_id=None, interface_number=None): List all the HID devices attached to the system, optionally filtering by vendor_id, product_id, and/or interface_number. - :returns: a list of matching DeviceInfo tuples. + :returns: a list of matching ``DeviceInfo`` tuples. """ results = [] @@ -192,7 +192,7 @@ def enumerate(vendor_id=None, product_id=None, interface_number=None): while d: if interface_number is None or interface_number == d.contents.interface: results.append(_DevInfoTuple(d.contents)) - d = d.contents.next + d = d.contents.next_device if devices: _api.hid_free_enumeration(devices) @@ -207,7 +207,7 @@ def open(vendor_id, product_id, serial=None): If no serial_number is provided, the first device with the specified ids is opened. - :returns: an opaque device handle, or None. + :returns: an opaque device handle, or ``None``. """ return _api.hid_open(vendor_id, product_id, serial) or None @@ -215,9 +215,10 @@ def open(vendor_id, product_id, serial=None): def open_path(device_path): """Open a HID device by its path name. - :param device_path: the path of a DeviceInfo tuple returned by enumerate(). + :param device_path: the path of a ``DeviceInfo`` tuple returned by + enumerate(). - :returns: an opaque device handle, or None. + :returns: an opaque device handle, or ``None``. """ return _api.hid_open_path(device_path) or None @@ -251,7 +252,7 @@ def write(device_handle, data): one exists. If it does not, it will send the data through the Control Endpoint (Endpoint 0). - :returns: True if the write was successful. + :returns: ``True`` if the write was successful. """ bytes_written = _api.hid_write(device_handle, c_char_p(data), len(data)) return bytes_written > -1 @@ -270,11 +271,10 @@ def read(device_handle, bytes_count, timeout_ms=-1): The first byte will contain the Report number if the device uses numbered reports. - :returns: the bytes read, or None if a timeout was reached. + :returns: the bytes read, or ``None`` if a timeout was reached. """ out_buffer = create_string_buffer('\x00' * (bytes_count + 1)) - bytes_read = _api.hid_read_timeout(device_handle, - out_buffer, bytes_count, timeout_ms) + bytes_read = _api.hid_read_timeout(device_handle, out_buffer, bytes_count, timeout_ms) if bytes_read > -1: return out_buffer[:bytes_read] @@ -299,12 +299,11 @@ def send_feature_report(device_handle, data, report_number=None): devices which do not use numbered reports), followed by the report data (16 bytes). - :returns: True if the report was successfully written to the device. + :returns: ``True`` if the report was successfully written to the device. """ if report_number is not None: data = chr(report_number) + data - bytes_written = _api.hid_send_feature_report( - device_handle, c_char_p(data), len(data)) + bytes_written = _api.hid_send_feature_report(device_handle, c_char_p(data), len(data)) return bytes_written > -1 @@ -320,8 +319,7 @@ def get_feature_report(device_handle, bytes_count, report_number=None): out_buffer = create_string_buffer('\x00' * (bytes_count + 2)) if report_number is not None: out_buffer[0] = chr(report_number) - bytes_read = _api.hid_get_feature_report( - device_handle, out_buffer, bytes_count) + bytes_read = _api.hid_get_feature_report(device_handle, out_buffer, bytes_count) if bytes_read > -1: return out_buffer[:bytes_read]