net.rim.device.api.system
Class USBPort

java.lang.Object
  |
  +--net.rim.device.api.system.IOPort
        |
        +--net.rim.device.api.system.USBPort

public final class USBPort
extends IOPort

Provides low-level access to the device's USB port.

You should avoid using this class in applications, as it is not portable. Rather, if you need to gain access to the USB port, use the CLDC Connector factory to serve a connection.

Note that access to the USB port is restricted by the application control ApplicationPermissions.PERMISSION_USB.

Since:
JDE 3.6.0

Constructor Summary
USBPort(int channel)
          Constructs a new USB object, opening the specified channel.
 
Method Summary
 void close()
          Closes the channel.
static void deregisterChannel(int channel)
          De-registers a channel.
static int getConnectionState()
          Retrieve the current USB connection state.
static int getMaximumRxSize()
          Retrive the maximum RX buffer size that can be registered.
static int getMaximumTxSize()
          Retrive the maximum TX buffer size that can be registered.
static boolean isSupported()
          Determines if the device has a serial port.
 int read()
          Reads single data byte from the receive buffer.
 int read(byte[] data)
          Reads data bytes from the receive buffer.
 int read(byte[] data, int offset, int length)
          Reads some data bytes from the receive buffer.
static int registerChannel(String name, int maxRxSize, int maxTxSize)
          Registers a channel.
 int write(byte[] data)
          Places bytes to send into the transmit buffer.
 int write(byte[] data, int offset, int length)
          Places some bytes to send into the transmit buffer.
 int write(int b)
          Places a single byte to send into the transmit buffer.
 
Methods inherited from class net.rim.device.api.system.IOPort
registerNotifyPattern
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

USBPort

public USBPort(int channel)
        throws IOException
Constructs a new USB object, opening the specified channel.
Parameters:
channel - The channel to open.
Throws:
IOException - If the port could not be opened.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0
Method Detail

close

public void close()
Closes the channel.

The system automatically invokes this method when the device is shut off. Applications may not assume that the channel is still open once the device is powered on again.

Overrides:
close in class IOPort
Throws:
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0

deregisterChannel

public static void deregisterChannel(int channel)
                              throws IOException
De-registers a channel.

Parameters:
channel - The channel handle.
Throws:
IOException - Thrown if an I/O error occurs.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0

getConnectionState

public static int getConnectionState()
Retrieve the current USB connection state.
Returns:
a bitwise OR of the USB_STATE values.
Since:
JDE 4.2.0

getMaximumRxSize

public static int getMaximumRxSize()
                            throws IOException
Retrive the maximum RX buffer size that can be registered.
Returns:
The maximum RX buffer size.
Throws:
IOException - Thrown if an I/O error occurs.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 4.2.0

getMaximumTxSize

public static int getMaximumTxSize()
                            throws IOException
Retrive the maximum TX buffer size that can be registered.
Returns:
The maximum TX buffer size.
Throws:
IOException - Thrown if an I/O error occurs.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 4.2.0

isSupported

public static boolean isSupported()
Determines if the device has a serial port.
Returns:
true if the device has a serial port.
Since:
JDE 3.6.0

read

public int read()
         throws IOException
Reads single data byte from the receive buffer.

Overrides:
read in class IOPort
Returns:
The byte read, or a negative number if an error occurred or no bytes were available.
Throws:
IOException - If the port is not currently open.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0

read

public int read(byte[] data)
         throws IOException
Reads data bytes from the receive buffer.

Overrides:
read in class IOPort
Parameters:
data - Buffer to contain the received bytes; to flush the receive buffer, pass null.
Returns:
Number of bytes placed in the data buffer.
Throws:
IOException - If the port is not currently open.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0

read

public int read(byte[] data,
                int offset,
                int length)
         throws IOException
Reads some data bytes from the receive buffer.

Invoke this method to stuff only a portion of your data buffer with bytes from the receive buffer.

Overrides:
read in class IOPort
Parameters:
data - Buffer to contain the received bytes; to flush the receive buffer, pass null.
offset - Position from the start of the buffer to begin stuffing bytes from the receive buffer.
length - Maximum number of bytes to read.
Returns:
Actual number of bytes placed in the receive buffer.
Throws:
IOException - If the port is not currently open.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0

registerChannel

public static int registerChannel(String name,
                                  int maxRxSize,
                                  int maxTxSize)
                           throws IOException
Registers a channel.
Parameters:
name - The name of the channel. Note that channel names starting with "RIM" are reserved for internal use. 3rd party applications registering a name that starts with "RIM" will receive a ControlledAccessException.
maxRxSize - The maximum receive size.
maxTxSize - The maximum transmit size.
Returns:
The channel handle.
Throws:
IOException - Thrown if an I/O error occurs.
ControlledAccessException - if application control forbids this operation or if the name of the channel is illegal, as defined above.
Since:
JDE 3.6.0

write

public int write(byte[] data)
          throws IOException
Places bytes to send into the transmit buffer.

Note that after calling this method, you must wait for the IOPortListener.dataSent() method to be invoked before writing additional data.

Overrides:
write in class IOPort
Parameters:
data - Bytes of data to send.
Returns:
Number of bytes placed in the buffer.
Throws:
IOException - If the port is not currently open.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0

write

public int write(byte[] data,
                 int offset,
                 int length)
          throws IOException
Places some bytes to send into the transmit buffer.

Note that after calling this method, you must wait for the IOPortListener.dataSent() method to be invoked before writing additional data.

Use this method to place only a portion of a byte array into the transmit buffer.

Overrides:
write in class IOPort
Parameters:
data - Bytes array containing data to send.
offset - First data byte from array to send.
length - Number of data bytes to send.
Returns:
Number of bytes actually placed in the buffer.
Throws:
IOException - If the port is not currently open.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0

write

public int write(int b)
          throws IOException
Places a single byte to send into the transmit buffer.

Overrides:
write in class IOPort
Parameters:
b - Byte of data to send.
Returns:
Numebr of bytes actually placed in the buffer (1 or 0).
Throws:
IOException - If the port is not currently open.
ControlledAccessException - if application control forbids this operation.
Since:
JDE 3.6.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.