usb.core
Interface DeviceSPI

All Known Subinterfaces:

RemoteDeviceSPI

All Known Implementing Classes:

DeviceImpl

public interface DeviceSPI

This is not an Application Programming Interface. It is used internally to the implementation, and connects to the host OS implementation (probably in native code).

Method Summary

void	claimInterface(int ifnum) Claims a particular interface in the current configuration.
int	clearHalt(byte ep) Clears halt/stall status on an endpoint.
Device	getChild(int port) Returns children of a hub device.
java.lang.String	getClaimer(int ifnum) Identifies the driver claiming a particular interface in the current configuration.
byte[]	getConfigBuf(int config) Returns a buffer holding the entire set of configuration descriptors for the specified configuration.
byte[]	readBulk(int ep, int length) Reads a specified number of bytes from a BULK IN endpoint.
byte[]	readControl(byte type, byte request, short value, short index, short length) Issues a control IN request with an optional data READ phase.
byte[]	readIntr(int ep, int len) Reads a specified number of bytes from a INTERRUPT IN endpoint.
void	releaseInterface(int ifnum) Releases a claim on a given interface, so that another driver can safely claim it.
void	setInterface(int ifnum, int alt) Assigns a particular alternate setting to a given interface.
void	writeBulk(int ep, byte[] buf) Writes a specified number of bytes to a BULK OUT endpoint.
void	writeControl(byte type, byte request, short value, short index, byte[] buf) Issues a control OUT request with an optional data WRITE phase.
void	writeIntr(int ep, byte[] buf) Writes a specified number of bytes to a INTERRUPT OUT endpoint.

Method Detail

getConfigBuf

public byte[] getConfigBuf(int config)
                    throws java.io.IOException

Returns a buffer holding the entire set of configuration descriptors for the specified configuration. The format of those descriptors is described in the USB 2.0 specification.

Parameters:

config - Number of the configuration, from zero to the limit specified by DeviceDescriptor.getNumConfigurations()

readControl

public byte[] readControl(byte type,
                          byte request,
                          short value,
                          short index,
                          short length)
                   throws java.io.IOException

Issues a control IN request with an optional data READ phase. The request goes to the default control endpoint (CONTROL IN zero). No interface needs to be claimed in order to issue control requests.

Most of the parameters here are used to build the SETUP packet for the control request, which is always written to the device. Note an OUT control request with only a setup packet is different from the IN request with the same bits in the setup packet data; it goes to a different endpoint.

Parameters:

type - Masked together using three constants from ControlMessage: DIR_TO_HOST, a TYPE_*, and a RECIP_*.

request - bRequest field, either standard (from table 9-3 in the USB 2.0 specification) for TYPE_STANDARD, or else as specified in the class or vendor device type specification.

value - sixteen bit field associated with request

index - sixteen bit field associated with request

length - How much data should be read; may be zero to indicate that no READ phase follows the SETUP packet.

Returns:

The data read from the device. If this is shorter than the requested length, the caller must determine whether to treat that as an error. For example, it's typical to request a full size string descriptor, expecting to get back only the bytes that exist, rather than read a partial descriptor to learn the size, and then reading the whole thing.

writeControl

public void writeControl(byte type,
                         byte request,
                         short value,
                         short index,
                         byte[] buf)
                  throws java.io.IOException

Issues a control OUT request with an optional data WRITE phase. The request goes to the default control endpoint (CONTROL OUT zero). No interface needs to be claimed in order to issue control requests.

Most of the parameters here are used to build the SETUP packet for the control request, which is always written to the device. Note an OUT control request with only a setup packet is different from the IN request with the same bits in the setup packet data; it goes to a different endpoint.

Parameters:

type - Masked together using three constants from ControlMessage: DIR_TO_DEVICE, a TYPE_*, and a RECIP_*.

request - bRequest field, either standard (from table 9-3 in the USB 2.0 specification) for TYPE_STANDARD, or else as specified in the class or vendor device type specification.

value - sixteen bit field associated with request

index - sixteen bit field associated with request

buf - The data to be written. Length may be zero to indicate that no WRITe phase follows the SETUP packet.

readBulk

public byte[] readBulk(int ep,
                       int length)
                throws java.io.IOException

Reads a specified number of bytes from a BULK IN endpoint. This may be fewer bytes than were requested; the caller must decide whether that's an error in this particular case. If this is an exact multiple of Endpoint.getMaxPacketSize(), the caller may need to decide whether to see if it is followed by a zero length packet.

An endpoint's interface should be claimed before it is used for bulk I/O.

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

length - How many bytes to read.

Returns:

The bytes actually read.

writeBulk

public void writeBulk(int ep,
                      byte[] buf)
               throws java.io.IOException

Writes a specified number of bytes to a BULK OUT endpoint. If this isn't an exact multiple of Endpoint.getMaxPacketSize() then the last packet is "short". To write such an exact multiple with a "short" last packet, explicitly follow this write by another, using a buffer with length zero.

An endpoint's interface should be claimed before it is used for bulk I/O.

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

buf - The bytes to write.

clearHalt

public int clearHalt(byte ep)
              throws java.io.IOException

Clears halt/stall status on an endpoint. Bulk and interrupt endpoints will stall to report some kinds of error. Clearing this status resets the "data toggle" at the USB protocol level, and re-enables I/O to the previously halted endpoint.

The endpoint's interface should be claimed before clearing its halt status.

Parameters:

ep - Endpoint address and direction, as returned by Endpoint.getEndpoint().

readIntr

public byte[] readIntr(int ep,
                       int len)
                throws java.io.IOException

Reads a specified number of bytes from a INTERRUPT IN endpoint. This may be fewer bytes than were requested; the caller must decide whether that's an error in this case.

This blocks until an interrupt transfer completes. It's the caller's responsibility to ensure that the endpoint is polled often enough to meet Endpoint.getInterval() requirements after a transfer completes.

An endpoint's interface should be claimed before it is used for interrupt I/O.

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

length - How many bytes to read.

Returns:

The bytes actually read.

writeIntr

public void writeIntr(int ep,
                      byte[] buf)
               throws java.io.IOException

Writes a specified number of bytes to a INTERRUPT OUT endpoint. If this isn't an exact multiple of Endpoint.getMaxPacketSize() then the last packet is "short". To write such an exact multiple with a "short" last packet, explicitly follow this write with a write of a buffer with length zero.

This blocks until an interrupt transfer completes. It's the caller's responsibility to ensure that the endpoint is polled often enough to meet Endpoint.getInterval() requirements after a transfer completes.

An endpoint's interface should be claimed before it is used for interrupt I/O.

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

buf - The bytes to write.

getClaimer

public java.lang.String getClaimer(int ifnum)
                            throws java.io.IOException

Identifies the driver claiming a particular interface in the current configuration. USB is oriented towards "interface drivers", where several different drivers can cooperate to handle different functions of a device. (An example might be an audio output connected to a speaker, and a HID control for input to a software mixer.)

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

Returns:

Driver name, or null to indicate the interface is not in use by any driver. Driver names are not standardized between host operating systems.

claimInterface

public void claimInterface(int ifnum)
                    throws java.io.IOException

Claims a particular interface in the current configuration. Might kick another driver off of that interface; avoid calling this unless no other driver has claimed it.

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

See Also:

releaseInterface(int)

setInterface

public void setInterface(int ifnum,
                         int alt)
                  throws java.io.IOException

Assigns a particular alternate setting to a given interface. These are often used to change characteristics such as throughput requirements or maximum packet sizes.

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

alt - Number from the descriptor, returned by Interface.getAlternateSetting().

releaseInterface

public void releaseInterface(int ifnum)
                      throws java.io.IOException

Releases a claim on a given interface, so that another driver can safely claim it.

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

See Also:

claimInterface(int)

getChild

public Device getChild(int port)
                throws java.io.IOException

Returns children of a hub device.

Parameters:

port - Number of the hub port of interest, from one to the Hub.getNumPorts().

Returns:

Device connected to that port, or null if there is no such device. Always returns null for devices that are not hubs.