documentation updates on hidapi

logitech/hidapi.py

@@ -18,14 +18,16 @@ __version__ = '0.2-hidapi-0.7.0'
 import os.path
 from collections import namedtuple
 
-from ctypes import (
+from ctypes import (cdll, create_string_buffer, create_unicode_buffer,
-				cdll, create_string_buffer, create_unicode_buffer,
+					c_int, c_ushort, c_size_t,
-				c_int, c_ushort, c_size_t,
+					c_char_p, c_wchar_p, c_void_p,
-				c_char_p, c_wchar_p, c_void_p,
+					POINTER, Structure)
-				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
+	This function initializes the HIDAPI library. Calling it is not strictly
-	strictly necessary, as it will be called automatically by
+	necessary, as it will be called automatically by enumerate() and any of the
-	hid_enumerate() and any of the hid_open_*() functions if it is
+	open_*() functions if it is needed.  This function should be called at the
-	needed.  This function should be called at the beginning of
+	beginning of execution however, if there is a chance of HIDAPI handles
-	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
+	This function frees all of the static data associated with HIDAPI. It should
-	HIDAPI. It should be called at the end of execution to avoid
+	be called at the end of execution to avoid memory leaks.
-	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,
+	bytes_read = _api.hid_read_timeout(device_handle, out_buffer, bytes_count, timeout_ms)
-		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(
+	bytes_written = _api.hid_send_feature_report(device_handle, c_char_p(data), len(data))
-									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(
+	bytes_read = _api.hid_get_feature_report(device_handle, out_buffer, bytes_count)
-									device_handle, out_buffer, bytes_count)
 	if bytes_read > -1:
 		return out_buffer[:bytes_read]