/** * Java libusb1.0 wrapper * Roger Millischer * * This library is covered by the LGPL, read LGPL.txt for details. */ package ch.ntb.inf.libusbJava; import ch.ntb.inf.libusbJava.exceptions.LibusbError; /** * This class represents the Java Native Interface to the shared library which * is (with some exceptions) a one-to-one representation of the libusb1.0 API.
*
*

Project Description

Java libusb1.0 is a Java wrapper for the * libusb1.0 USB library. * * libusb aim is to create a library for * use by user level applications to access USB devices regardless of OS.
* Libusb-Windows * backend aim of this project is to bring a Windows backend to the mainline * libusb 1.0 branch, so that libusb 1.0 can easily be used on Windows * platforms. The library allows user space applications to access any USB * device on Windows in a generic way without writing any line of kernel driver * code.
*
* The API description of this class has been copied from the libusb-1.0 API * Reference and adapted where neccessary.
* */ public class LibusbJava1 { /** * Set message verbosity. * * * The default level is 0, which means no messages are ever printed. If you * choose to increase the message verbosity level, ensure that your * application does not close the stdout/stderr file descriptors.
*
* You are advised to set level 3. libusb is conservative with its message * logging and most of the time, will only log messages that explain error * conditions and other oddities. This will help you debug your software.
*
* If the LIBUSB_DEBUG environment variable was set when libusb was * initialized, this function does nothing: the message verbosity is fixed * to the value in the environment variable.
*
* If libusb was compiled without any message logging, this function does * nothing: you'll never get any messages.
*
* If libusb was compiled with verbose debug message logging, this function * does nothing: you'll always get messages from all levels.
*
* * @param ctx * the context to operate on, or NULL for the default context * @param level * debug level to set */ public static native void libusb_set_debug(long ctx, int level); /** * Initialize libusb.
*
* This function must be called before calling any other libusb function.
*
* * @return a context to operate on * @throws LibusbError * if an error occured */ public static native long libusb_init() throws LibusbError; /** * Deinitialize libusb.
*
* Should be called after closing all open devices and before your * application terminates.
*
* * @param ctx * the context to deinitialize, or 0 if the default context has * been used. */ public static native void libusb_exit(long ctx); /** * Returns a list of USB devices currently attached to the system.
*
* This is your entry point into finding a USB device to operate.
*
* * @param ctx * the context to operate on, or NULL for the default context * * @return Usb_Devices currently attached to the system
* if no device is attached the devnum of the returned device is set * to -1
* or NULL if an error occurs */ public static native Usb_Device libusb_get_device_list(long ctx); /** * Get the number of the bus that a device is connected to. * * @param dev * a device * @return the bus number */ public static native short libusb_get_bus_number(Usb_Device dev); /** * Calculate the maximum packet size which a specific endpoint is capable is * sending or receiving in the duration of 1 microframe.
*
* Only the active configution is examined. The calculation is based on the * wMaxPacketSize field in the endpoint descriptor as described in section * 9.6.6 in the USB 2.0 specifications.
*
* If acting on an isochronous or interrupt endpoint, this function will * multiply the value found in bits 0:10 by the number of transactions per * microframe (determined by bits 11:12). Otherwise, this function just * returns the numeric value found in bits 0:10.
*
* This function is useful for setting up isochronous transfers, for example * you might pass the return value from this function to * libusb_set_iso_packet_lengths() in order to set the length * field of every isochronous packet in a transfer.
*
* Since libusb v1.0.3.
*
* This functionality is not available on Windows-Systems
*
* * @param dev * a device * @param endpoint * address of the endpoint in question * @return the maximum packet size which can be sent/received on this * endpoint
* LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist
* LIBUSB_ERROR_OTHER on other failure
* TODO wenn funktion impl. richtig verlinken @see * libusb_set_iso_packet_lengths() */ public static native int libusb_get_max_iso_packet_size(Usb_Device dev, short endpoint); /** * Increment the reference count of a device. * * @param dev * the device to reference * @return the same device */ public static native Usb_Device libusb_ref_device(Usb_Device dev); /** * Decrement the reference count of a device.
*
* If the decrement operation causes the reference count to reach zero, the * device shall be destroyed.
*
* * @param dev * the device to unreference */ public static native void libusb_unref_device(Usb_Device dev); /** * Open a device and obtain a device handle.
*
* A handle allows you to perform I/O on the device in question.
*
* Internally, this function adds a reference to the device and makes it * available to you through libusb_get_device(). This reference * is removed during libusb_close().
*
* This is a non-blocking function; no requests are sent over the bus.
*
* * @param dev * the device to open * * @return a device handle >= 0 * * @throws LibusbError * in case of an error
* Possible causes are:
* - ERROR_NO_MEM on memory allocation failure
* - ERROR_ACCESS if the user has insufficient permissions
* - ERROR_NO_DEVICE if the device has been disconnected
* - another ERROR code on other failure * * @see #libusb_get_device(long) */ public static native long libusb_open(Usb_Device dev) throws LibusbError; /** * Convenience function for finding a device with a particular * idVendor/idProduct combination.
*
* This function is intended for those scenarios where you are using libusb * to knock up a quick test application - it allows you to avoid calling * libusb_get_device_list() and worrying about * traversing/freeing the list.
*
* This function has limitations and is hence not intended for use in real * applications: if multiple devices have the same IDs it will only give you * the first one, etc.
* * @param ctx * the context to operate on, or NULL for the default context * @param vendor_id * the idVendor value to search for * @param product_id * the idProduct value to search for * @return a handle for the first found device, or NULL on error or if the * device could not be found. * @see #libusb_get_device_list(long) */ public static native long libusb_open_device_with_vid_pid(long ctx, int vendor_id, int product_id); /** * Close a device handle.
*
* Should be called on all open handles before your application exits.
*
* Internally, this function destroys the reference that was added by * libusb_open() on the given device.
*
* This is a non-blocking function; no requests are sent over the bus.
*
* * @param dev_handle * the handle to close */ public static native void libusb_close(long dev_handle); /** * Get the underlying device for a handle.
*
* This function does not modify the reference count of the returned device, * so do not feel compelled to unreference it when you are done.
*
* * @param dev_handle * a device handle * @return the underlying {@link Usb_Device} */ public static native Usb_Device libusb_get_device(long dev_handle); /** * Determine the bConfigurationValue of the currently active configuration.
*
* You could formulate your own control request to obtain this information, * but this function has the advantage that it may be able to retrieve the * information from operating system caches (no I/O involved).
*
* If the OS does not cache this information, then this function will block * while a control transfer is submitted to retrieve the information.
*
* This function will return a value of 0 if the device is in unconfigured * state.
*
* * @param dev_handle * a device handle * @return bConfigurationValue of the currently active configuration * @throws LibusbError * in case of an error
* Possible error causes are:
* - ERROR_NO_DEVICE if the device has been disconnected - * another ERROR code on other failure */ public static native int libusb_get_configuration(long dev_handle) throws LibusbError; /** * Set the active configuration for a device.
*
* The operating system may or may not have already set an active * configuration on the device. It is up to your application to ensure the * correct configuration is selected before you attempt to claim interfaces * and perform other operations.
*
* If you call this function on a device already configured with the * selected configuration, then this function will act as a lightweight * device reset: it will issue a SET_CONFIGURATION request using the current * configuration, causing most USB-related device state to be reset * (altsetting reset to zero, endpoint halts cleared, toggles reset).
*
* You cannot change/reset configuration if your application has claimed * interfaces - you should free them with * {@link #libusb_release_interface(long, int)} first. You cannot * change/reset configuration if other applications or drivers have claimed * interfaces.
*
* A configuration value of -1 will put the device in unconfigured state. * The USB specifications state that a configuration value of 0 does this, * however buggy devices exist which actually have a configuration 0.
*
* You should always use this function rather than formulating your own * SET_CONFIGURATION control request. This is because the underlying * operating system needs to know when such changes happen.
*
* This is a blocking function.
*
* * @param dev_handle * a device handle * @param configuration * the bConfigurationValue of the configuration you wish to * activate, or -1 if you wish to put the device in unconfigured * state * @throws LibusbError * in case of an error
* Possible error causes are:
* - ERROR_NOT_FOUND if the requested configuration does not * exist
* - ERROR_BUSY if interfaces are currently claimed
* - ERROR_NO_DEVICE if the device has been disconnected
* - another LIBUSB_ERROR code on other failure
*/ public static native void libusb_set_configuration(long dev_handle, int configuration) throws LibusbError; /** * Claim an interface on a given device handle.
*
* You must claim the interface you wish to use before you can perform I/O * on any of its endpoints.
*
* It is legal to attempt to claim an already-claimed interface, in which * case libusb just returns 0 without doing anything.
*
* Claiming of interfaces is a purely logical operation, it does not cause * any requests to be sent over the bus. Interface claiming is used to * instruct the underlying operating system that your application wishes to * take ownership of the interface.
*
* This is a non-blocking function.
*
* * @param dev_handle * a device handle * @param interface_number * the bInterfaceNumber of the interface you wish to claim * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if the interface was not claimed
* - ERROR_NO_DEVICE if the device has been disconnected
* - ERROR_BUSY if another program or driver has claimed the * interface
* - another LIBUSB_ERROR code on other failure
*/ public static native void libusb_claim_interface(long dev_handle, int interface_number) throws LibusbError; /** * Release an interface previously claimed with * {@link #libusb_claim_interface(long, int)}.
*
* You should release all claimed interfaces before closing a device handle.
*
* This is a blocking function. A SET_INTERFACE control request will be sent * to the device, resetting interface state to the first alternate setting.
*
* * @param dev_handle * a device handle * @param interface_number * the bInterfaceNumber of the previously-claimed interface * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if the interface was not claimed
* - ERROR_NO_DEVICE if the device has been disconnected
* - another ERROR code on other failure
*/ public static native void libusb_release_interface(long dev_handle, int interface_number) throws LibusbError; /** * Activate an alternate setting for an interface.
*
* The interface must have been previously claimed with * {@link #libusb_claim_interface(long, int)}.
*
* You should always use this function rather than formulating your own * SET_INTERFACE control request. This is because the underlying operating * system needs to know when such changes happen.
*
* This is a blocking function.
*
* * @param dev_handle * a device handle * @param interface_number * the bInterfaceNumber of the previously-claimed interface * @param alternate_setting * the bAlternateSetting of the alternate setting to activate * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if the interface was not claimed, or the * requested alternate setting does not exist
* - ERROR_NO_DEVICE if the device has been disconnected
* - another LIBUSB_ERROR code on other failure
*/ public static native void libusb_set_interface_alt_setting(long dev_handle, int interface_number, int alternate_setting) throws LibusbError; /** * Clear the halt/stall condition for an endpoint.
*
* Endpoints with halt status are unable to receive or transmit data until * the halt condition is stalled.
*
* You should cancel all pending transfers before attempting to clear the * halt condition.
*
* This is a blocking function.
*
* * @param dev_handle * a device handle * @param endpoint * the endpoint to clear halt status * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if the endpoint does not exist
* - ERROR_NO_DEVICE if the device has been disconnected
* - another LIBUSB_ERROR code on other failure
*/ public static native void libusb_clear_halt(long dev_handle, short endpoint) throws LibusbError; /** * Perform a USB port reset to reinitialize a device.
*
* The system will attempt to restore the previous configuration and * alternate settings after the reset has completed.
*
* If the reset fails, the descriptors change, or the previous state cannot * be restored, the device will appear to be disconnected and reconnected. * This means that the device handle is no longer valid (you should close * it) and rediscover the device. A return code of LIBUSB_ERROR_NOT_FOUND * indicates when this is the case.
*
* This is a blocking function which usually incurs a noticeable delay.
*
* * @param dev_handle * a handle of the device to reset * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if re-enumeration is required, or if the * device has been disconnected
* - another LIBUSB_ERROR code on other failure
*/ public static native void libusb_reset_device(long dev_handle) throws LibusbError; /** * Determine if a kernel driver is active on an interface.
*
* If a kernel driver is active, you cannot claim the interface, and libusb * will be unable to perform I/O.
*
* * @param dev_handle * a device handle * @param interface_number * the interface to check * @return 0 if no kernel driver is active
* 1 if a kernel driver is active
* @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NO_DEVICE if the device has been disconnected
* - another LIBUSB_ERROR code on other failure
* @see #libusb_detach_kernel_driver(long, int) */ public static native int libusb_kernel_driver_active(long dev_handle, int interface_number) throws LibusbError; /** * Detach a kernel driver from an interface.
*
* If successful, you will then be able to claim the interface and perform * I/O.
*
* * @param dev_handle * a device handle * @param interface_number * the interface to detach the driver from * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if no kernel driver was active
* - ERROR_INVALID_PARAM if the interface does not exist
* - ERROR_NO_DEVICE if the device has been disconnected
* - another ERROR code on other failure
* @see #libusb_kernel_driver_active(long, int) */ public static native void libusb_detach_kernel_driver(long dev_handle, int interface_number) throws LibusbError; /** * Re-attach an interface's kernel driver, which was previously detached * using {@link #libusb_detach_kernel_driver(long, int)}.
* * @param dev_handle * a device handle * @param interface_number * the interface to attach the driver from * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if no kernel driver was active
* - ERROR_INVALID_PARAM if the interface does not exist
* - ERROR_NO_DEVICE if the device has been disconnected
* - ERROR_BUSY if the driver cannot be attached because the * interface is claimed by a program or driver
* - another ERROR code on other failure
* @see #libusb_kernel_driver_active(long, int) */ public static native void libusb_attach_kernel_driver(long dev_handle, int interface_number) throws LibusbError; /** * Get the USB configuration descriptor for the currently active * configuration.
*
* This is a non-blocking function which does not involve any requests being * sent to the device.
*
* * @param dev * a device * @return {@link Usb_Config_Descriptor} */ public static native Usb_Config_Descriptor libusb_get_active_config_descriptor( Usb_Device dev); /** * Retrieve a string descriptor in C style ASCII.
*
* Wrapper around * {@link #libusb_get_string_descriptor(long, short, int, int)}. Uses the * first language supported by the device. * * @param dev_handle * a device handle * @param desc_index * the index of the descriptor to retrieve * @param size * number of charactes which will be retrieved (the length of the * resulting String) * @return a string which contains the string descriptor * @throws LibusbError * in case of an error
*/ public static native String libusb_get_string_descriptor_ascii( long dev_handle, short desc_index, int size) throws LibusbError; /** * Retrieve a descriptor from the default control pipe.
*
* This is a convenience function which formulates the appropriate control * message to retrieve the descriptor. * * @param dev_handle * a device handle * @param desc_type * the descriptor type * @param desc_index * the index of the descriptor to retrieve * @param size * number of bytes which will be retrieved (the length of the * resulting byte[]) * @return a byte[] which contains the descriptor or null on failure * @throws LibusbError * in case of an error
* */ public static native byte[] libusb_get_descriptor(long dev_handle, int desc_type, short desc_index, int size) throws LibusbError; /** * Retrieve a descriptor from a device.
*
* This is a convenience function which formulates the appropriate control * message to retrieve the descriptor. The string returned is Unicode, as * detailed in the USB specifications. * * @param dev_handle * a device handle * @param desc_index * the index of the descriptor to retrieve * @param langid * the language ID for the string descriptor * @param size * number of charactes which will be retrieved (the length of the * resulting String) * @return a string which contains the string descriptor * @throws LibusbError * in case of an error
* @see #libusb_get_string_descriptor_ascii(long, short, int) */ public static native String libusb_get_string_descriptor(long dev_handle, short desc_index, int langid, int size) throws LibusbError; /** * Allocate a libusb transfer with a specified number of isochronous packet * descriptors.
* * The returned transfer is pre-initialized for you. When the new transfer * is no longer needed, it should be freed with * libusb_free_transfer().
*
* Transfers intended for non-isochronous endpoints (e.g. control, bulk, * interrupt) should specify an iso_packets count of zero.
*
* For transfers intended for isochronous endpoints, specify an appropriate * number of packet descriptors to be allocated as part of the transfer. The * returned transfer is not specially initialized for isochronous I/O you * are still required to set the num_iso_packets and type * fields accordingly.
*
* It is safe to allocate a transfer with some isochronous packets and then * use it on a non-isochronous endpoint. If you do this, ensure that at time * of submission, num_iso_packets is 0 and that type is set appropriately.
* * @param iso_packets * number of isochronous packet descriptors to allocate * @return a newly allocated transfernumber, or NULL on error */ public static native long libusb_alloc_transfer(int iso_packets); /** * Free a transfer. * * This should be called for all transfers allocated with * libusb_alloc_transfer().
*
* It is legal to call this function with a NULL transfer. In this case, the * function will simply return safely.
*
* It is not legal to free an active transfer (one which has been submitted * and has not yet completed).
*
* * @param transfernumber * the transfer to free */ public static native void libusb_free_transfer(long transfernumber); /** * Submit a transfer.
*
* This function will fire off the USB transfer and then return immediately.
*
* * @param transfernumber * the transfer to submit * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NO_DEVICE if the device has been disconnected
* - ERROR_BUSY if the transfer has already been submitted.
* - another LIBUSB_ERROR code on other failure
*/ public static native void libusb_submit_transfer(long transfernumber) throws LibusbError; /** * Asynchronously cancel a previously submitted transfer.
*
* This function returns immediately, but this does not indicate * cancellation is complete. Libusb_event will be invoked at some later time * to notify you. * * @param transfernumber * a transfer * @throws LibusbError * in case of an error
* Possible causes for errors are:
* - ERROR_NOT_FOUND if the transfer is already complete or * cancelled.
* - a LIBUSB_ERROR code on failure
*/ public static native void libusb_cancel_transfer(long transfernumber) throws LibusbError; /** * Get the data section of a control transfer.
*
* This convenience function is here to remind you that the data does not * start until 8 bytes into the actual buffer, as the setup packet comes * first.
*
* Calling this function only makes sense from a transfer event handler, or * situations where you have already allocated a suitably sized buffer. * * @param transfernumber * a transfer * @return the data section from the transfer, null if the transfer number * was invalid. */ public static native byte[] libusb_control_transfer_get_data( long transfernumber); /** * Get the control setup packet of a control transfer.
*
* This convenience function is here to remind you that the control setup * occupies the first 8 bytes of the transfer data buffer.
*
* Calling this function only makes sense from a transfer event handler, or * situations where you have already allocated a suitably sized buffer at * transfer->buffer. * * @param transfernumber * a transfer * @return the setup packet from the transfer, null if the transfer number * was invalid. */ public static native byte[] libusb_control_transfer_get_setup( long transfernumber); /** * Helper function to populate the setup packet (first 8 bytes of the data * buffer) for a control transfer.
* * @param bmRequestType * @param bRequest * @param wValue * @param wIndex * @param wLength * @return the setup packet */ public static native byte[] libusb_fill_control_setup(int bmRequestType, int bRequest, int wValue, int wIndex, int wLength); /** * Helper function to populate the required libusb_transfer fields for a * control transfer.
*
* If you pass a transfer buffer to this function, the first 8 bytes will be * interpreted as a control setup packet, and the wLength field will be used * to automatically populate the length field of the transfer. Therefore the * recommended approach is:
*
* 1. Call libusb_fill_control_setup()
* 2. Allocate a suitably sized data buffer (including space for control * setup)
* 3. Put the retrieved setup packet into the firste 8 byte of the data * buffer.
* 4. If this is a host-to-device transfer with a data stage, put the data * in place after the setup packet
* 5. Call this function
* 6. Call libusb_submit_transfer()
*
* It is also legal to pass a NULL buffer to this function, in which case * this function will not attempt to populate the length field. Remember * that you must then populate the buffer and length fields later. * * @param transfernumber * transfer to populate * @param dev_handle * handle of the device that * @param buffer * data buffer. If provided, this function will interpret the * first 8 bytes as a setup packet and infer the transfer length * from that. * @param timeout * timeout for the transfer in milliseconds */ public static native void libusb_fill_control_transfer(long transfernumber, long dev_handle, byte[] buffer, int timeout); /** * Helper function to populate the required libusb_transfer fields for a * bulk transfer. * * @param transfernumber * the transfer to populate * @param dev_handle * handle of the device that will handle the transfer * @param endpoint * address of the endpoint where this transfer will be sent * @param buffer * data buffer * @param length * length of data buffer * @param timeout * timeout for the transfer in milliseconds */ public static native void libusb_fill_bulk_transfer(long transfernumber, long dev_handle, byte endpoint, byte[] buffer, int length, int timeout); /** * Helper function to populate the required libusb_transfer fields for an * interrupt transfer. * * @param transfernumber * the transfer to populate * @param dev_handle * handle of the device that will handle the transfer * @param endpoint * address of the endpoint where this transfer will be sent * @param buffer * data buffer * @param length * length of data buffer * @param timeout * timeout for the transfer in milliseconds */ public static native void libusb_fill_interrupt_transfer( long transfernumber, long dev_handle, byte endpoint, byte[] buffer, int length, int timeout); /** * Helper function to populate the required libusb_transfer fields for an * isochronous transfer. * * @param transfernumber * the transfer to populate * @param dev_handle * handle of the device that will handle the transfer * @param endpoint * address of the endpoint where this transfer will be sent * @param buffer * data buffer * @param length * length of data buffer * @param num_iso_packets * the number of isochronous packets * @param timeout * timeout for the transfer in milliseconds */ public static native void libusb_fill_iso_transfer(long transfernumber, long dev_handle, byte endpoint, byte[] buffer, int length, int num_iso_packets, int timeout); /** * Convenience function to set the length of all packets in an isochronous * transfer, based on the num_iso_packets field in the transfer structure. * * @param transfer * a transfer * @param length * the length to set in each isochronous packet descriptor */ public static native void libusb_set_iso_packet_lengths(long transfer, int length); /** * Convenience function to locate the position of an isochronous packet * within the buffer of an isochronous transfer.
*
* This is a thorough function which loops through all preceding packets, * accumulating their lengths to find the position of the specified packet. * Typically you will assign equal lengths to each packet in the transfer, * and hence the above method is sub-optimal. You may wish to use * libusb_get_iso_packet_buffer_simple() instead.
*
* * @param transfer * a transfer * @param packet * the packet to return * @return the packet buffer inside the transfer buffer, or NULL if the * packet does not exist */ public static native byte[] libusb_get_iso_packet_buffer(long transfer, int packet); /** * Convenience function to locate the position of an isochronous packet * within the buffer of an isochronous transfer, for transfers where each * packet is of identical size.
*
* This function relies on the assumption that every packet within the * transfer is of identical size to the first packet. Calculating the * location of the packet buffer is then just a simple calculation: buffer + * (packet_size * packet)
*
* Do not use this function on transfers other than those that have * identical packet lengths for each packet. * * @param transfernumber * a transfer * @param packet * he packet to return * @return the packet buffer inside the transfer buffer, or NULL if the * packet does not exist. */ public static native byte[] libusb_get_iso_packet_buffer_simple( long transfernumber, int packet); /** * Attempt to acquire the event handling lock.
*
* This lock is used to ensure that only one thread is monitoring libusb * event sources at any one time.
*
* You only need to use this lock if you are developing an application which * calls poll() or select() on libusb's file descriptors directly. If you * stick to libusb's event handling loop functions (e.g. * libusb_handle_events()) then you do not need to be concerned * with this locking.
*
* While holding this lock, you are trusted to actually be handling events. * If you are no longer handling events, you must call * libusb_unlock_events() as soon as possible. * * @param ctx * the context to operate on, or NULL for the default context * @return 0 if the lock was obtained successfully
* 1 if the lock was not obtained (i.e. another thread holds the * lock)
*/ public static native int libusb_try_lock_events(long ctx); /** * Acquire the event handling lock, blocking until successful acquisition if * it is contended.
*
* This lock is used to ensure that only one thread is monitoring libusb * event sources at any one time.
*
* You only need to use this lock if you are developing an application which * calls poll() or select() on libusb's file descriptors directly. If you * stick to libusb's event handling loop functions (e.g. * libusb_handle_events()) then you do not need to be concerned * with this locking.
*
* While holding this lock, you are trusted to actually be handling events. * If you are no longer handling events, you must call * libusb_unlock_events() as soon as possible. * * @param ctx * the context to operate on, or NULL for the default context */ public static native void libusb_lock_events(long ctx); /** * Release the lock previously acquired with * libusb_try_lock_events() or * libusb_lock_events().
*
* Releasing this lock will wake up any threads blocked on * libusb_wait_for_event(). * * @param ctx * the context to operate on, or NULL for the default context */ public static native void libusb_unlock_events(long ctx); /** * Determine if it is still OK for this thread to be doing event handling.
*
* Sometimes, libusb needs to temporarily pause all event handlers, and this * is the function you should use before polling file descriptors to see if * this is the case.
*
* If this function instructs your thread to give up the events lock, you * should just continue the usual logic. On the next iteration, your thread * will fail to obtain the events lock, and will hence become an event * waiter.
*
* This function should be called while the events lock is held: you don't * need to worry about the results of this function if your thread is not * the current event handler. * * @param ctx * the context to operate on, or NULL for the default context * @return 1 if event handling can start or continue
* 0 if this thread must give up the events lock
*/ public static native int libusb_event_handling_ok(long ctx); /** * Determine if an active thread is handling events (i.e. if anyone is * holding the event handling lock). * * @param ctx * the context to operate on, or NULL for the default context * @return 1 if a thread is handling events
* 0 if there are no threads currently handling events
*/ public static native int libusb_event_handler_active(long ctx); /** * Acquire the event waiters lock.
*
* This lock is designed to be obtained under the situation where you want * to be aware when events are completed, but some other thread is event * handling so calling libusb_handle_events() is not allowed.
*
* You then obtain this lock, re-check that another thread is still handling * events, then call libusb_wait_for_event().
*
* You only need to use this lock if you are developing an application which * calls poll() or select() on libusb's file descriptors directly, and may * potentially be handling events from 2 threads simultaenously. If you * stick to libusb's event handling loop functions (e.g. * libusb_handle_events()) then you do not need to be concerned * with this locking. * * @param ctx * the context to operate on, or NULL for the default context */ public static native void libusb_lock_event_waiters(long ctx); /** * Release the event waiters lock. * * @param ctx * the context to operate on, or NULL for the default context */ public static native void libusb_unlock_event_waiters(long ctx); /** * Wait for another thread to signal completion of an event.
*
* Must be called with the event waiters lock held, see * libusb_lock_event_waiters().
*
* This function will block until any of the following conditions are met:
* * 1. The timeout expires
* 2. A transfer completes
* 3. A thread releases the event handling lock through * libusb_unlock_events()
*
* Condition 1 is obvious. Condition 2 unblocks your thread after the * callback for the transfer has completed. Condition 3 is important because * it means that the thread that was previously handling events is no longer * doing so, so if any events are to complete, another thread needs to step * up and start event handling.
*
* This function releases the event waiters lock before putting your thread * to sleep, and reacquires the lock as it is being woken up. * * @param ctx * the context to operate on, or NULL for the default context * @param timeval * maximum timeout in seconds for this blocking function. 0 * seconds indicates unlimited timeout * @return 0 after a transfer completes or another thread stops event * handling
* 1 if the timeout expired
*/ public static native int libusb_wait_for_event(long ctx, long timeval); /** * Handle any pending events.
*
* libusb determines "pending events" by checking if any timeouts have * expired and by checking the set of file descriptors for activity.
*
* If a zero timeval is passed, this function will handle any * already-pending events and then immediately return in non-blocking style.
*
* If a non-zero timeval is passed and no events are currently pending, this * function will block waiting for events to handle up until the specified * timeout. If an event arrives or a signal is raised, this function will * return early. * * @param ctx * the context to operate on, or NULL for the default context * @param timeval * the maximum time to block waiting for events, or zero for * non-blocking mode * @throws LibusbError * in case of an error
*/ public static native void libusb_handle_events_timeout(long ctx, long timeval) throws LibusbError; /** * Handle any pending events in blocking mode with a sensible timeout.
*
* This timeout is currently hardcoded at 2 seconds but we may change this * if we decide other values are more sensible. For finer control over * whether this function is blocking or non-blocking, or the maximum * timeout, use libusb_handle_events_timeout() instead. * * @param ctx * the context to operate on, or NULL for the default context * @throws LibusbError * in case of an error
*/ public static native void libusb_handle_events(long ctx) throws LibusbError; /** * Handle any pending events by polling file descriptors, without checking * if any other threads are already doing so.
*
* Must be called with the event lock held, see * libusb_lock_events().
*
* This function is designed to be called under the situation where you have * taken the event lock and are calling poll()/select() directly on libusb's * file descriptors (as opposed to using libusb_handle_events() * or similar). You detect events on libusb's descriptors, so you then call * this function with a zero timeout value (while still holding the event * lock). * * @param ctx * the context to operate on, or NULL for the default context * @param timeval * the maximum time in seconds to block waiting for events, or * zero for non-blocking mode * @throws LibusbError * in case of an error
*/ public static native void libusb_handle_events_locked(long ctx, long timeval) throws LibusbError; /** * Determines whether your application must apply special timing * considerations when monitoring libusb's file descriptors.
*
* This function is only useful for applications which retrieve and poll * libusb's file descriptors in their own main loop (The more advanced * option).
*
* Ordinarily, libusb's event handler needs to be called into at specific * moments in time (in addition to times when there is activity on the file * descriptor set). The usual approach is to use * libusb_get_next_timeout() to learn about when the next * timeout occurs, and to adjust your poll()/select() timeout accordingly so * that you can make a call into the library at that time.
*
* Some platforms supported by libusb do not come with this baggage - any * events relevant to timing will be represented by activity on the file * descriptor set, and libusb_get_next_timeout() will always * return 0. This function allows you to detect whether you are running on * such a platform.
*
* Since v1.0.5. * * @param ctx * the context to operate on, or NULL for the default context * @return 0 if you must call into libusb at times determined by * libusb_get_next_timeout(), or 1 if all timeout * events are handled internally or through regular activity on the * file descriptors. */ public static native int libusb_pollfds_handle_timeouts(long ctx); /** * Determine the next internal timeout that libusb needs to handle.
*
* You only need to use this function if you are calling poll() or select() * or similar on libusb's file descriptors yourself - you do not need to use * it if you are calling libusb_handle_events() or a variant directly.
*
* You should call this function in your main loop in order to determine how * long to wait for select() or poll() to return results. libusb needs to be * called into at this timeout, so you should use it as an upper bound on * your select() or poll() call.
*
* When the timeout has expired, call into libusb_handle_events_timeout() * (perhaps in non-blocking mode) so that libusb can handle the timeout.
*
* This function may return an zero timevalue. If this is the case, it * indicates that libusb has a timeout that has already expired so you * should call libusb_handle_events_timeout() or similar immediately. A * return code of -1 indicates that there are no pending timeouts.
*
* On some platforms, this function will always returns -1 (no pending * timeouts). * * @param ctx * the context to operate on, or NULL for the default context * @return time to next timeout
* -1 if there are no pending timeouts
* @throws LibusbError * If an error is occured in libusb */ public static native int libusb_get_next_timeout(long ctx) throws LibusbError; /** * Register notification functions for file descriptor additions/removals.
*
* These functions will be invoked for every new or removed file descriptor * that libusb uses as an event source.
*
* To remove notifiers, set remove TRUE.
*
* Note that file descriptors may have been added even before you register * these notifiers (e.g. at libusb_init() time).
*
* Additionally, note that the removal notifier may be called during * libusb_exit() (e.g. when it is closing file descriptors that * were opened and added to the poll set at libusb_init() * time).
* If you don't want this, remove the notifiers immediately before calling * libusb_exit(). * * @param ctx * the context to operate on, or NULL for the default context * @param remove * select add or remove notifiers */ public static native void libusb_set_pollfd_notifiers(long ctx, boolean remove); /** * Retrieve a array of file descriptors that should be polled by your main * loop as libusb event sources.
*
* * The actual list contents must not be touched. * * @param ctx * the context to operate on, or NULL for the default context * @return array of Libusb_pollfd or NULL on error */ public static native Libusb_pollfd[] libusb_get_pollfds(long ctx); /** * Perform a USB control transfer.
*
* The direction of the transfer is inferred from the bmRequestType field of * the setup packet.
*
* The wValue, wIndex and wLength fields values should be given in * host-endian byte order. * * @param dev_handle * a handle for the device to communicate with * @param bmRequestType * the request type field for the setup packet * @param bRequest * the request field for the setup packet * @param wValue * the value field for the setup packet * @param wIndex * the index field for the setup packet * @param data * a suitably-sized data buffer for either input or output * (depending on direction bits within bmRequestType) * @param wLength * the length field for the setup packet. The data buffer should * be at least this size. * @param timeout * timeout (in millseconds) that this function should wait before * giving up due to no response being received. For an unlimited * timeout, use value 0. * @return on success, the number of bytes actually transferred
* LIBUSB_ERROR_TIMEOUT if the transfer timed out
* LIBUSB_ERROR_PIPE if the control request was not supported by the * device
* LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
* another LIBUSB_ERROR code on other failures */ public static native int libusb_control_transfer(long dev_handle, int bmRequestType, int bRequest, int wValue, int wIndex, byte[] data, int wLength, int timeout); /** * Perform a USB bulk transfer.
*
* The direction of the transfer is inferred from the direction bits of the * endpoint address.
*
* For bulk reads, the length field indicates the maximum length of data you * are expecting to receive. If less data arrives than expected, this * function will return that data, so be sure to check the returned value.
*
* You should also check this value for bulk writes. Not all of the data may * have been written. * * @param dev_handle * a handle for the device to communicate with * @param endpoint * the address of a valid endpoint to communicate with * @param data * a suitably-sized data buffer for either input or output * (depending on endpoint) * @param length * for bulk writes, the number of bytes from data to be sent. for * bulk reads, the maximum number of bytes to receive into the * data buffer. * @param timeout * timeout (in millseconds) that this function should wait before * giving up due to no response being received. For an unlimited * timeout, use value 0. * @return The number of bytes actually transferred * @throws LibusbError * in case an error occured
* Possible causes are:
* - ERROR_TIMEOUT if the transfer timed out
* - ERROR_PIPE if the control request was not supported by the * device
* - ERROR_OVERFLOW if the device offered more data
* - ERROR_NO_DEVICE if the device has been disconnected
* - another code on other failures. */ public static native int libusb_bulk_transfer(long dev_handle, byte endpoint, byte[] data, int length, int timeout) throws LibusbError; /** * Perform a USB interrupt transfer.
*
* The direction of the transfer is inferred from the direction bits of the * endpoint address.
*
* For bulk reads, the length field indicates the maximum length of data you * are expecting to receive. If less data arrives than expected, this * function will return that data, so be sure to check the returned value.
*
* You should also check this value for bulk writes. Not all of the data may * have been written.
*
* The default endpoint bInterval value is used as the polling interval. * * @param dev_handle * a handle for the device to communicate with * @param endpoint * the address of a valid endpoint to communicate with * @param data * a suitably-sized data buffer for either input or output * (depending on endpoint) * @param length * for bulk writes, the number of bytes from data to be sent. for * bulk reads, the maximum number of bytes to receive into the * data buffer. * @param timeout * timeout (in millseconds) that this function should wait before * giving up due to no response being received. For an unlimited * timeout, use value 0. * @return The number of bytes actually transferred
* @throws LibusbError * in case an error occured
* Possible causes are:
* - ERROR_TIMEOUT if the transfer timed out
* - ERROR_PIPE if the control request was not supported by the * device
* - ERROR_OVERFLOW if the device offered more data
* - ERROR_NO_DEVICE if the device has been disconnected
* - another ERROR code on other failures */ public static native int libusb_interrupt_transfer(long dev_handle, byte endpoint, byte[] data, int length, int timeout) throws LibusbError; /** * Returns the error string after an error occured. * * @return the last error sring. */ public static native String libusb_strerror(); static { String os = System.getProperty("os.name"); if (os.contains("Windows")) { System.loadLibrary("LibusbJava-1_0"); } else { System.loadLibrary("usbJava-1.0"); } /* * After loading the library, we register a "shutdown hook" to be called * for cleaning up stuff in the library when exiting. */ Runtime.getRuntime().addShutdownHook(new Thread() { public void run() { try { LibusbJava1.teardown(); } catch (Exception e) { e.printStackTrace(); } } }); /* * After setting up the cleanup callback, it's now safe to call the code * that initializes stuff in the native library */ int setup_result = setup(); if (setup_result < 0) { throw new UnsatisfiedLinkError("Could not setup the library. (" + setup_result + ")"); } } /** * This method is used to setup stuff in the native library. After calling * this function, {@link #teardown()} has to be called if the native library * is not used anymore. * * @return - 0 if successful - <0 if an error occured */ private static native int setup(); /** * This method cleans up stuff initialized using {@link #setup()}. */ private static native void teardown(); }