sparrowwallet/usb4java
sparrowwallet/usb4java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Correct and add missing JavaDoc.

Browse Source
This commit is contained in:
Klaus Reimer 2013-09-14 21:20:52 +02:00
parent d21b59d488
commit d15ce2ae02
11 changed files with 518 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/main/java/de/ailis/usb4java/libusb/ConfigDescriptor.java
View File

@ -42,7 +42,8 @@ public final class ConfigDescriptor implements UsbConfigurationDescriptor
/**
* Constructs a new config descriptor which can be passed to the
* {@link LibUsb#getConfigDescriptor(Device, int, ConfigDescriptor)} method.
* {@link LibUsb#getConfigDescriptor(Device, byte, ConfigDescriptor)}
* method.
*/
public ConfigDescriptor()
{

97
src/main/java/de/ailis/usb4java/libusb/ControlSetup.java
View File

@ -23,10 +23,33 @@ import java.nio.ByteOrder;
import de.ailis.usb4java.utils.BufferUtils;
/**
* Setup packet for control transfers.
*
* @author Luca Longinotti (l@longi.li)
*/
public final class ControlSetup
{
/**
* The native data structure of the setup packet.
*
* USB Control Setup is always 8 bytes long. Structured as follows:
*
* byte 0: bmRequestType
* byte 1: bRequest
* bytes 2-3: wValue (Little Endian)
* bytes 4-5: wIndex (Little Endian)
* bytes 6-7: wLength (Little Endian)
*/
private final ByteBuffer controlSetup;
/**
* Constructs a new control setup packet using the first 8 bytes from the
* specified transfer buffer.
*
* @param buffer
* The transfer buffer.
*/
ControlSetup(final ByteBuffer buffer)
{
if (buffer == null)
@ -42,60 +65,118 @@ public final class ControlSetup
}
/**
* USB Control Setup is always 8 bytes long.
* Structured as follows:
* byte 0: bmRequestType
* byte 1: bRequest
* bytes 2-3: wValue (Little Endian)
* bytes 4-5: wIndex (Little Endian)
* bytes 6-7: wLength (Little Endian)
* Returns the request type.
*
* Bits 0:4 determine recipient.
* Bits 5:6 determine type.
* Bit 7 determines data transfer direction.
*
* @return The request type.
*/
public byte bmRequestType()
{
return this.controlSetup.get(0);
}
/**
* Sets the request type.
*
* @param bmRequestType
* The request type to set.
*/
public void setBmRequestType(final byte bmRequestType)
{
this.controlSetup.put(0, bmRequestType);
}
/**
* Returns the request.
*
* If the type bits of {@link #bmRequestType()} are equal to
* {@link LibUsb#REQUEST_TYPE_STANDARD} then this field refers to
* one of the REQUEST_* constants or {@link LibUsb#SET_ISOCH_DELAY}. For
* other cases, use of this field is application-specific.
*
* @return The request.
*/
public byte bRequest()
{
return this.controlSetup.get(1);
}
/**
* Sets the request.
*
* @param bRequest
* The request to set.
*/
public void setBRequest(final byte bRequest)
{
this.controlSetup.put(1, bRequest);
}
/**
* Returns the value.
*
* Varies according to request
*
* @return The value.
*/
public short wValue()
{
return this.controlSetup.getShort(2);
}
/**
* Sets the value.
*
* @param wValue
* The value to set.
*/
public void setWValue(final short wValue)
{
this.controlSetup.putShort(2, wValue);
}
/**
* Returns the index.
*
* Varies according to request, typically used to pass an index or offset
*
* @return The index.
*/
public short wIndex()
{
return this.controlSetup.getShort(4);
}
/**
* Sets the index.
*
* @param wIndex
* The index to set.
*/
public void setWIndex(final short wIndex)
{
this.controlSetup.putShort(4, wIndex);
}
/**
* Returns the number of bytes to transfer.
*
* @return The number of bytes to transfer.
*/
public short wLength()
{
return this.controlSetup.getShort(6);
}
/**
* Sets the number of bytes to transfer.
*
* @param wLength
* The number of bytes to transfer.
*/
public void setWLength(final short wLength)
{
this.controlSetup.putShort(6, wLength);

32
src/main/java/de/ailis/usb4java/libusb/HotplugCallback.java
View File

@ -5,7 +5,39 @@
package de.ailis.usb4java.libusb;
/**
* Hotplug callback..
*
* When requesting hotplug event notifications, you pass a callback of this
* type.
*/
public interface HotplugCallback
{
/**
* Process a hotplug event.
*
* This callback may be called by an internal event thread and as such it
* is recommended the callback do minimal processing before returning.
*
* libusb will call this function later, when a matching event had happened
* on a matching device.
*
* It is safe to call either
* {@link LibUsb#hotplugRegisterCallback(Context, int, int, int, int, int,
* HotplugCallback, Object, HotplugCallbackHandle)} or
* {@link LibUsb#hotplugDeregisterCallback(Context, HotplugCallbackHandle)}
* from within a callback.
*
* @param context
* Context of this notification.
* @param device
* Device this event occurred on.
* @param event
* Event that occurred.
* @param userData
* user data provided when this callback was registered
* @return Whether this callback is finished processing events. Returning 1
* will cause this callback to be deregistered.
*/
int processEvent(Context context, Device device, int event, Object userData);
}

12
src/main/java/de/ailis/usb4java/libusb/HotplugCallbackHandle.java
View File

@ -21,10 +21,10 @@ package de.ailis.usb4java.libusb;
/**
* Hotplug Callback Handle.
*
* Callback handles are generated by {@link LibUsb#hotplugRegisterCallback(Context,
* int, int, short, short, byte, HotplugCallback, Object, HotplugCallbackHandle)}
* and can be used to deregister callbacks. Callback handles are unique
* per {@link Context} and it is safe to call
* Callback handles are generated by {@link LibUsb#hotplugRegisterCallback(
* Context, int, int, int, int, int, HotplugCallback, Object,
* HotplugCallbackHandle)} and can be used to deregister callbacks. Callback
* handles are unique per {@link Context} and it is safe to call
* {@link LibUsb#hotplugDeregisterCallback(Context, HotplugCallbackHandle)}
* on an already deregistered callback.
*
@ -37,8 +37,8 @@ public final class HotplugCallbackHandle
/**
* Constructs a new hotplug callback handle. Must be passed to
* {@link LibUsb#hotplugRegisterCallback(Context, int, int, short, short,
* byte, HotplugCallback, Object, HotplugCallbackHandle)} before passing it
* {@link LibUsb#hotplugRegisterCallback(Context, int, int, int, int, int,
* HotplugCallback, Object, HotplugCallbackHandle)} before passing it
* to any other method.
*/
public HotplugCallbackHandle()

24
src/main/java/de/ailis/usb4java/libusb/IsoPacketDescriptor.java
View File

@ -18,6 +18,9 @@
package de.ailis.usb4java.libusb;
/**
* Isochronous packet descriptor.
*/
public final class IsoPacketDescriptor
{
/** The native pointer to the descriptor structure. */
@ -42,15 +45,36 @@ public final class IsoPacketDescriptor
return this.isoPacketDescriptorPointer;
}
/**
* Returns the length of data to request in this packet.
*
* @return The length of data to request in this packet.
*/
public native int length();
/**
* Sets the length of data to request in this packet.
*
* @param length
* The length to set.
*/
// Theoretically the right representation for a C unsigned int would be a
// Java long, but the maximum length for ISO Packets is 1024 bytes, so an
// int more than suffices to hold any possible valid values here.
public native void setLength(final int length);
/**
* Returns the amount of data that was actually transferred.
*
* @return The amount of data that was actually transferred.
*/
public native int actualLength();
/**
* Returns the status code for this packet.
*
* @return The status code for this packet.
*/
public native int status();
@Override

315
src/main/java/de/ailis/usb4java/libusb/LibUsb.java
View File

@ -266,6 +266,7 @@ public final class LibUsb
*/
public static final int CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101;
/** The size of a control setup packet. */
public static final short CONTROL_SETUP_SIZE = 8;
// Device and/or Interface Class codes.
@ -482,6 +483,7 @@ public final class LibUsb
// Values for bits 2:3 of the bmAttributes field in
// EndpointDescriptor.
/** The mask used to filter out sync types from attributes. */
public static final byte ISO_SYNC_TYPE_MASK = 0x0C;
/** No synchronization. */
@ -499,6 +501,7 @@ public final class LibUsb
// Usage type for isochronous endpoints. Values for bits 4:5 of the
// bmAttributes field in EndpointDescriptor.
/** The mask used to filter out usage types from attributes. */
public static final byte ISO_USAGE_TYPE_MASK = 0x30;
/** Data endpoint. */
@ -616,11 +619,12 @@ public final class LibUsb
/** Match any vendorId or productId or deviceClass. */
public static final int HOTPLUG_MATCH_ANY = -1;
/** The next global hotplug ID to use. */
private static long globalHotplugId = 1;
/**
* Hotplug callbacks (to correctly manage calls and additional data).
*/
private static long globalHotplugId = 1;
private static final ConcurrentMap<Long, ImmutablePair<HotplugCallback, Object>> hotplugCallbacks =
new ConcurrentHashMap<Long, ImmutablePair<HotplugCallback, Object>>();
@ -814,7 +818,7 @@ public final class LibUsb
* Get the the parent from the specified device [EXPERIMENTAL].
*
* Please note that the reference count of the returned device is not
* increased. As such, do not *ever* call {@link #unrefDevice(Device))
* increased. As such, do not *ever* call {@link #unrefDevice(Device)}
* directly on the returned Device.
*
* @param device
@ -858,7 +862,7 @@ public final class LibUsb
* isochronous transfers, but a design mistake resulted in this function
* instead. It simply returns the wMaxPacketSize value without considering
* its contents. If you're dealing with isochronous transfers, you probably
* want {@link #getMaxIsoPacketSize(Device, int)} instead.
* want {@link #getMaxIsoPacketSize(Device, byte)} instead.
*
* @param device
* A device.
@ -986,7 +990,7 @@ public final class LibUsb
* Get the underlying device for a handle.
*
* Please note that the reference count of the returned device is not
* increased. As such, do not *ever* call {@link #unrefDevice(Device))
* increased. As such, do not *ever* call {@link #unrefDevice(Device)}
* directly on the returned Device.
*
* @param handle
@ -1417,7 +1421,7 @@ public final class LibUsb
/**
* A simple wrapper around
* {@link #getStringDescriptorAscii(DeviceHandle, int, StringBuffer)}.
* {@link #getStringDescriptorAscii(DeviceHandle, byte, StringBuffer)}.
* It simply returns the string (maximum length of 127) if possible. If not
* possible (NULL handle or 0-index specified or error occured) then null is
* returned.
@ -1464,7 +1468,7 @@ public final class LibUsb
* @return 0 on success, {@link #ERROR_NOT_FOUND} if the device is in
* unconfigured state another ERROR code on error
*
* @see #getConfigDescriptor(Device, int, ConfigDescriptor)
* @see #getConfigDescriptor(Device, byte, ConfigDescriptor)
*/
public static native int getActiveConfigDescriptor(final Device device,
final ConfigDescriptor descriptor);
@ -1487,7 +1491,7 @@ public final class LibUsb
* not exist another ERROR code on error.
*
* @see #getActiveConfigDescriptor(Device, ConfigDescriptor)
* @see #getConfigDescriptorByValue(Device, int, ConfigDescriptor)
* @see #getConfigDescriptorByValue(Device, byte, ConfigDescriptor)
*/
public static native int getConfigDescriptor(final Device device,
final byte index, final ConfigDescriptor descriptor);
@ -1511,14 +1515,14 @@ public final class LibUsb
* not exist another ERROR code on error See also:
*
* @see #getActiveConfigDescriptor(Device, ConfigDescriptor)
* @see #getConfigDescriptor(Device, int, ConfigDescriptor)
* @see #getConfigDescriptor(Device, byte, ConfigDescriptor)
*/
public static native int getConfigDescriptorByValue(final Device device,
final byte value, final ConfigDescriptor descriptor);
/**
* Free a configuration descriptor obtained from
* {@link #getConfigDescriptor(Device, int, ConfigDescriptor)} or
* {@link #getConfigDescriptor(Device, byte, ConfigDescriptor)} or
* {@link #getActiveConfigDescriptor(Device, ConfigDescriptor)}.
*
* It is safe to call this function with a NULL config parameter, in which
@ -1733,7 +1737,7 @@ public final class LibUsb
* @param data
* Output buffer for descriptor.
* @return number of bytes returned in data, or LIBUSB_ERROR code on failure
* @see #getStringDescriptorAscii(DeviceHandle, int, StringBuffer)
* @see #getStringDescriptorAscii(DeviceHandle, byte, StringBuffer)
*/
public static int getStringDescriptor(final DeviceHandle handle,
final byte index, final short langId, final ByteBuffer data)
@ -2154,20 +2158,20 @@ public final class LibUsb
* 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
* {@link #getNextTimeout(Context, IntBuffer)} to learn about when the next
* {@link #getNextTimeout(Context, LongBuffer)} 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 {@link #getNextTimeout(Context, IntBuffer)} will
* descriptor set, and {@link #getNextTimeout(Context, LongBuffer)} will
* always return 0. This function allows you to detect whether you are
* running on such a platform.
*
* @param context
* The context to operate on, or NULL for the default context
* @return 0 if you must call into libusb at times determined by
* {@link #getNextTimeout(Context, IntBuffer)}, or 1 if all timeout
* {@link #getNextTimeout(Context, LongBuffer)}, or 1 if all timeout
* events are handled internally or through regular activity on the
* file descriptors.
*/
@ -2358,7 +2362,7 @@ public final class LibUsb
* 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 call the {@link Transfer#setNumIsoPackets(int)} a
* {@link Transfer#setType(int)} methods accordingly.
* {@link Transfer#setType(byte)} methods 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
@ -2397,11 +2401,11 @@ public final class LibUsb
*
* @param transfer
* The transfer to submit
* @return 0 on success, {@link #LIBUSB_ERROR_NO_DEVICE} if the device has
* @return 0 on success, {@link #ERROR_NO_DEVICE} if the device has
* been
* disconnected, {@link #LIBUSB_ERROR_BUSY} if the transfer has
* disconnected, {@link #ERROR_BUSY} if the transfer has
* already been
* submitted. {@link #LIBUSB_ERROR_NOT_SUPPORTED} if the transfer
* submitted. {@link #ERROR_NOT_SUPPORTED} if the transfer
* flags are
* not supported by the operating system. Another LIBUSB_ERROR code
* on failure.
@ -2414,27 +2418,76 @@ public final class LibUsb
* This function returns immediately, but this does not indicate
* cancellation
* is complete. Your callback function will be invoked at some later time
* with a transfer status of {@link #LIBUSB_TRANSFER_CANCELLED}.
* with a transfer status of {@link #TRANSFER_CANCELLED}.
*
* @param transfer
* The transfer to cancel
* @return 0 on success, {@link #LIBUSB_ERROR_NOT_FOUND} if the transfer is
* @return 0 on success, {@link #ERROR_NOT_FOUND} if the transfer is
* already complete or cancelled. Another LIBUSB_ERROR code on
* failure.
*/
public static native int cancelTransfer(final Transfer transfer);
/**
* 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 callback function,
* or situations where you have already allocated a suitably sized buffer at
* {@link Transfer#buffer()}.
*
* @param transfer
* A transfer.
* @return The data section.
*/
public static ByteBuffer controlTransferGetData(final Transfer transfer)
{
return BufferUtils.slice(transfer.buffer(), CONTROL_SETUP_SIZE,
transfer.buffer().limit() - CONTROL_SETUP_SIZE);
}
/**
* 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 callback function,
* or situations where you have already allocated a suitably sized buffer at
* {@link Transfer#buffer()}.
*
* @param transfer
* A transfer.
* @return The setup section.
*/
public static ControlSetup controlTransferGetSetup(final Transfer transfer)
{
return new ControlSetup(transfer.buffer());
}
/**
* Helper function to populate the setup packet (first 8 bytes of the data
* buffer) for a control transfer.
*
* The wIndex, wValue and wLength values should be given in host-endian byte
* order.
*
* @param buffer
* Buffer to output the setup packet into.
* @param bmRequestType
* See {@link ControlSetup#bmRequestType()}.
* @param bRequest
* See {@link ControlSetup#bRequest()}.
* @param wValue
* See {@link ControlSetup#wValue()}.
* @param wIndex
* See {@link ControlSetup#wIndex()}.
* @param wLength
* See {@link ControlSetup#wLength()}.
*/
public static void fillControlSetup(final ByteBuffer buffer,
final byte bmRequestType, final byte bRequest, final short wValue,
final short wIndex, final short wLength)
@ -2447,6 +2500,47 @@ public final class LibUsb
setup.setWLength(wLength);
}
/**
* Helper function to populate the required {@link 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. Allocate a suitably sized data buffer (including space for control
* setup).
*
* 2. Call
* {@link #fillControlSetup(ByteBuffer, byte, byte, short, short, short)}.
*
* 3. If this is a host-to-device transfer with a data stage, put the data
* in place after the setup packet.
*
* 4. Call this function.
*
* 5. Call {@link #submitTransfer(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 transfer
* The transfer to populate.
* @param handle
* Handle of the device that will handle the transfer.
* @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 callback
* callback function to be invoked on transfer completion.
* @param userData
* User data to pass to callback function.
* @param timeout
* Timeout for the transfer in milliseconds.
*/
public static void fillControlTransfer(final Transfer transfer,
final DeviceHandle handle, final ByteBuffer buffer,
final TransferCallback callback, final Object userData,
@ -2465,6 +2559,25 @@ public final class LibUsb
transfer.setLength(CONTROL_SETUP_SIZE + (setup.wLength() & 0xFFFF));
}
/**
* Helper function to populate the required {@link Transfer} fields for a
* bulk transfer.
*
* @param transfer
* The transfer to populate.
* @param 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 callback
* Callback function to be invoked on transfer completion.
* @param userData
* User data to pass to callback function.
* @param timeout
* Timeout for the transfer in milliseconds.
*/
public static void fillBulkTransfer(final Transfer transfer,
final DeviceHandle handle, final byte endpoint,
final ByteBuffer buffer, final TransferCallback callback,
@ -2479,6 +2592,25 @@ public final class LibUsb
transfer.setCallback(callback);
}
/**
* Helper function to populate the required {@link Transfer} fields for an
* interrupt transfer.
*
* @param transfer
* The transfer to populate.
* @param 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 callback
* Callback function to be invoked on transfer completion.
* @param userData
* User data to pass to callback function.
* @param timeout
* Timeout for the transfer in milliseconds.
*/
public static void fillInterruptTransfer(final Transfer transfer,
final DeviceHandle handle, final byte endpoint,
final ByteBuffer buffer, final TransferCallback callback,
@ -2493,6 +2625,27 @@ public final class LibUsb
transfer.setCallback(callback);
}
/**
* Helper function to populate the required {@link Transfer} fields for an
* isochronous transfer.
*
* @param transfer
* The transfer to populate.
* @param 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 numIsoPackets
* The number of isochronous packets.
* @param callback
* Callback function to be invoked on transfer completion.
* @param userData
* User data to pass to callback function.
* @param timeout
* Timeout for the transfer in milliseconds.
*/
public static void fillIsoTransfer(final Transfer transfer,
final DeviceHandle handle, final byte endpoint,
final ByteBuffer buffer, final int numIsoPackets,
@ -2509,6 +2662,16 @@ public final class LibUsb
transfer.setCallback(callback);
}
/**
* Convenience function to set the length of all packets in an isochronous
* transfer, based on the {@link Transfer#numIsoPackets()} field.
*
* @param transfer
* A transfer.
* @param length
* The length to set in each isochronous packet descriptor.
* @see #getMaxPacketSize(Device, byte)
*/
public static void setIsoPacketLengths(final Transfer transfer,
final int length)
{
@ -2518,6 +2681,24 @@ public final class LibUsb
}
}
/**
* 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
* {@link #getIsoPacketBufferSimple(Transfer, int)} instead.
*
* @param transfer
* A transfer.
* @param packet
* The packet to return the address of.
* @return The base address of the packet buffer inside the transfer buffer,
* or NULL if the packet does not exist.
* @see #getIsoPacketBufferSimple(Transfer, int)
*/
public static ByteBuffer getIsoPacketBuffer(final Transfer transfer,
final int packet)
{
@ -2538,6 +2719,27 @@ public final class LibUsb
isoDescriptors[packet].length());
}
/**
* 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 transfer
* A transfer.
* @param packet
* The packet to return the address of.
* @return The base address of the packet buffer inside the transfer buffer,
* or NULL if the packet does not exist.
* @see #getIsoPacketBuffer(Transfer, int)
*/
public static ByteBuffer getIsoPacketBufferSimple(final Transfer transfer,
final int packet)
{
@ -2553,6 +2755,20 @@ public final class LibUsb
isoDescriptors[packet].length());
}
/**
* Processes a hotplug event from native code.
*
* @param context
* Context of this notification.
* @param device
* The device this event occurred on.
* @param event
* Event that occurred
* @param hotplugId
* The hotplug ID.
* @return Whether this callback is finished processing events. Returning 1
* will cause this callback to be deregistered.
*/
static int hotplugCallback(final Context context, final Device device,
final int event, final long hotplugId)
{
@ -2589,26 +2805,25 @@ public final class LibUsb
* events.
*
* @param context
* context to register this callback with
* Context to register this callback with.
* @param events
* bitwise or of events that will trigger this callback
* Bitwise or of events that will trigger this callback.
* @param flags
* hotplug callback flags
* Hotplug callback flags.
* @param vendorId
* the vendor id to match or {@link #HOTPLUG_MATCH_ANY}
* The vendor id to match or {@link #HOTPLUG_MATCH_ANY}.
* @param productId
* the product id to match or {@link #HOTPLUG_MATCH_ANY}
* The product id to match or {@link #HOTPLUG_MATCH_ANY}.
* @param deviceClass
* the device class to match or {@link #HOTPLUG_MATCH_ANY}
* The device class to match or {@link #HOTPLUG_MATCH_ANY}.
* @param callback
* the function to be invoked on a matching event/device
* The function to be invoked on a matching event/device
* @param userData
* user data to pass to the callback function
* @param handle
* hotplug callback handle of the allocated callback. Only needed
* User data to pass to the callback function.
* @param callbackHandle
* Hotplug callback handle of the allocated callback. Only needed
* if you later want to deregister this callback, can be NULL.
*
* @return LIBUSB_SUCCESS on success LIBUSB_ERROR code on failure
* @return {@link #SUCCESS} on success, some ERROR code on failure.
*/
public static synchronized int hotplugRegisterCallback(
final Context context, final int events, final int flags,
@ -2644,6 +2859,28 @@ public final class LibUsb
return result;
}
/**
* Internally called native method for registering a hotplug callback.
*
* @param context
* Context to register this callback with.
* @param events
* Bitwise or of events that will trigger this callback.
* @param flags
* Hotplug callback flags.
* @param vendorId
* The vendor id to match or {@link #HOTPLUG_MATCH_ANY}.
* @param productId
* The product id to match or {@link #HOTPLUG_MATCH_ANY}.
* @param deviceClass
* The device class to match or {@link #HOTPLUG_MATCH_ANY}.
* @param callbackHandle
* Hotplug callback handle of the allocated callback. Only needed
* if you later want to deregister this callback, can be NULL.
* @param hotplugId
* The hotplug callback ID.
* @return {@link #SUCCESS} on success, some ERROR code on failure.
*/
static native int hotplugRegisterCallbackNative(final Context context,
final int events, final int flags, final int vendorId,
final int productId, final int deviceClass,
@ -2657,7 +2894,7 @@ public final class LibUsb
*
* @param context
* context this callback is registered with
* @param handle
* @param callbackHandle
* the handle of the callback to deregister
*/
public static void hotplugDeregisterCallback(final Context context,
@ -2678,6 +2915,18 @@ public final class LibUsb
hotplugCallbacks.remove(handle);
}
/**
* Internally called native method for unregistering a hotplug callback.
*
* Deregister a callback from a {@link Context}. This function is safe to
* call from within a hotplug callback.
*
* @param context
* context this callback is registered with
* @param callbackHandle
* the handle of the callback to deregister
* @return The hotplug callback ID.
*/
static native long hotplugDeregisterCallbackNative(final Context context,
final HotplugCallbackHandle callbackHandle);
}

20
src/main/java/de/ailis/usb4java/libusb/Transfer.java
View File

@ -35,9 +35,11 @@ public final class Transfer
/** The native pointer to the transfer structure. */
private long transferPointer;
// Keeping a reference to the buffer has multiple benefits: faster get(), GC
// prevention (while Transfer is alive) and you can check the buffer's
// original capacity (needed to check setLength() properly).
/**
* Keeping a reference to the buffer has multiple benefits: faster get(), GC
* prevention (while Transfer is alive) and you can check the buffer's
* original capacity (needed to check setLength() properly).
*/
private ByteBuffer transferBuffer;
/**
@ -187,6 +189,12 @@ public final class Transfer
this.setLengthNative(length);
}
/**
* Native method called internally to set the length of the data buffer.
*
* @param length
* The length to set.
*/
native void setLengthNative(final int length);
/**
@ -267,6 +275,12 @@ public final class Transfer
this.transferBuffer = buffer;
}
/**
* Native method called internally to set the data buffer.
*
* @param buffer
* The data buffer to set.
*/
native void setBufferNative(final ByteBuffer buffer);
/**

17
src/main/java/de/ailis/usb4java/libusb/TransferCallback.java
View File

@ -5,7 +5,24 @@
package de.ailis.usb4java.libusb;
/**
* Asynchronous transfer callback.
*
* When submitting asynchronous transfers, you pass a callback of this type via
* the callback member of the {@link Transfer} structure.
*
* @author Luca Longinotti (l@longi.li)
*/
public interface TransferCallback
{
/**
* Processes a transfer notification.
*
* libusb will call this function later, when the transfer has completed or
* failed.
*
* @param transfer
* The {@link Transfer} the callback is being notified about.
*/
void processTransfer(Transfer transfer);
}

40
src/main/java/de/ailis/usb4java/utils/BufferUtils.java
View File

@ -9,26 +9,66 @@ import java.nio.ByteBuffer;
import java.nio.IntBuffer;
import java.nio.LongBuffer;
/**
* Provides some utility methods for working with {@link IntBuffer} and
* {@link ByteBuffer}.
*
* @author Luca Longinotti (l@longi.li)
*/
public final class BufferUtils
{
/** The native size of the type <code>int</code>. */
private static final int intSize = Integer.SIZE / Byte.SIZE;
/** The native size of the type <code>long</code>. */
private static final int longSize = Long.SIZE / Byte.SIZE;
/**
* Allocates a new direct {@link ByteBuffer} with the specified size and
* returns it.
*
* @param bytes
* The size of the new byte buffer.
* @return The allocated direct byte buffer.
*/
public static ByteBuffer allocateByteBuffer(final int bytes)
{
return ByteBuffer.allocateDirect(bytes);
}
/**
* Allocates a new {@link IntBuffer} with space for exactly one integer
* value.
*
* @return The allocated int buffer.
*/
public static IntBuffer allocateIntBuffer()
{
return ByteBuffer.allocateDirect(intSize).asIntBuffer();
}
/**
* Allocates a new {@link LongBuffer} with space for exactly one long value.
*
* @return The allocated long buffer.
*/
public static LongBuffer allocateLongBuffer()
{
return ByteBuffer.allocateDirect(longSize).asLongBuffer();
}
/**
* Slices a part of the specified {@link ByteBuffer} into a new byte buffer
* and returns it.
*
* @param buffer
* The byte buffer to slice data from.
* @param offset
* The offset of the part to slice.
* @param length
* The length of the part to slice.
* @return The new byte buffer with the sliced part.
*/
public static ByteBuffer slice(final ByteBuffer buffer, final int offset,
final int length)
{

4
src/test/java/de/ailis/usb4java/libusb/LibUSBGlobalTest.java
View File

@ -105,8 +105,8 @@ public class LibUSBGlobalTest
}
/**
* Checks the {@link LibUsb#le16ToCpu(int)} and
* {@link LibUsb#cpuToLe16(int)} methods.
* Checks the {@link LibUsb#le16ToCpu(short)} and
* {@link LibUsb#cpuToLe16(short)} methods.
*/
@Test
public void testEndianConversion()

14
src/test/java/de/ailis/usb4java/libusb/TransferTest.java
View File

@ -105,7 +105,7 @@ public class TransferTest
/**
* Tests the {@link Transfer#setDevHandle(DeviceHandle)} and
* {@link Transfer#getDevHandle()} methods.
* {@link Transfer#devHandle()} methods.
*/
@Test
public void testDevHandle()
@ -128,7 +128,7 @@ public class TransferTest
}
/**
* Tests the {@link Transfer#setFlags(byte)} and {@link Transfer#getFlags()}
* Tests the {@link Transfer#setFlags(byte)} and {@link Transfer#flags()}
* methods.
*/
@Test
@ -146,7 +146,7 @@ public class TransferTest
/**
* Tests the {@link Transfer#setEndpoint(byte)} and
* {@link Transfer#getEndpoint()} methods.
* {@link Transfer#endpoint()} methods.
*/
@Test
public void testEndpoint()
@ -162,7 +162,7 @@ public class TransferTest
}
/**
* Tests the {@link Transfer#setType(byte)} and {@link Transfer#getType()}
* Tests the {@link Transfer#setType(byte)} and {@link Transfer#type()}
* methods.
*/
@Test
@ -179,8 +179,8 @@ public class TransferTest
}
/**
* Tests the {@link Transfer#setTimeout(int)} and
* {@link Transfer#getTimeout()} methods.
* Tests the {@link Transfer#setTimeout(long)} and
* {@link Transfer#timeout()} methods.
*/
@Test
public void testTimeout()
@ -196,7 +196,7 @@ public class TransferTest
}
/**
* Tests the {@link Transfer#getStatus()} methods.
* Tests the {@link Transfer#status()} methods.
*/
@Test
public void testGetStatus()