com.starmicronics.stario
Class StarIOPort

java.lang.Object
  extended bycom.starmicronics.stario.StarIOPort

public class StarIOPort
extends java.lang.Object

This class provides a communications API for Star Micronics's printers. It supports serial, parallel, usb, and ethernet based printers, and hides most of the low level behavioral differences inherent in those different communication forms.


Method Summary
 StarPrinterStatus beginCheckedBlock()
          This method initiates a checked block printing operation and returns the device's detailed status.
 StarPrinterStatus endCheckedBlock()
          This method ends a checked block printing operation and returns the device's detailed status.
protected  void finalize()
           
static StarIOPort getPort(java.lang.String portName, java.lang.String portSettings, int ioTimeoutMillis)
          This method opens a connection to the specified port.
 java.lang.String getPortName()
          This method returns the port name as it was originally specified.
 java.lang.String getPortSettings()
          This method returns the port settings as they were originally specified.
 int readPort(byte[] readBuffer, int offset, int size)
          This method reads data from the device.
static void releasePort(StarIOPort port)
          This function closes a connection to the port specified.
 void resetDevice()
          This method resets the device at the hardware level.
 StarPrinterStatus retreiveStatus()
          This method retreives the device's detailed status.
 int writePort(byte[] writeBuffer, int offset, int size)
          This method writes data to the device.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getPort

public static StarIOPort getPort(java.lang.String portName,
                                 java.lang.String portSettings,
                                 int ioTimeoutMillis)
                          throws StarIOPortException
This method opens a connection to the specified port.

Parameters:
portName - is the name of the port to open
On Windows this parameter takes on one for the following forms:
"usbven:" which opens the first available USB Vendor Class device
"usbven:sNsNsNsN" which opens the USB Vendor Class device with that serial number
"usbven:COMx" which opens the USB Vendor Class device that has been assigned to COMx (i.e. 'COM4' or 'COM17')
"usbprn:Queue Name" which opens the USB Printer Class device associated with the specified printer queue
"COMx" which opens the real serial port (i.e. 'COM1')
"LPTx" which opens the real parallel port (i.e. 'LPT1')
"tcp:nnn.nnn.nnn.nnn" which opens the network printer at the specified IP address (i.e. '192.168.11.3')
portSettings - gives the port settings - "9600,n,8,1,h" for serial, "" for all others
In the case of serial, the portSettings string contains the following fields:
baud: 38400, 19200, 9600, 4800, 2400
parity: n, e, o
data-bits: 8, 7
stop-bits: 1
flow-ctrl: n, h
ioTimeoutMillis - millisecond timeout controlling internally used communication APIs (this parameter garantees that all of the below APIs will complete in a bounded amount of time, but does NOT garantee the exact timeout length)
Throws:
StarIOPortException - when a communication failure occurs.
You should retry if the exception's getIsPortInUseFailure method returns true, which indicates that another process is using the port.

releasePort

public static void releasePort(StarIOPort port)
This function closes a connection to the port specified.

Parameters:
port - StarIOPorttype representing previously created port

getPortName

public java.lang.String getPortName()
This method returns the port name as it was originally specified.

Returns:
the originally specified port name

getPortSettings

public java.lang.String getPortSettings()
This method returns the port settings as they were originally specified.

Returns:
the originally specified port settings

writePort

public int writePort(byte[] writeBuffer,
                     int offset,
                     int size)
              throws StarIOPortException
This method writes data to the device.

Parameters:
writeBuffer - contains the output data
offset - specifies where to begin pulling data from writeBuffer - zero-based offset
size - number of bytes to write
Returns:
The number of bytes that were actually written. Under some interface types, this function will succeed even when no data was written out. Your application should call this function a limited number of times until all the data has been written out or until an application determined retry threshold has been reached.
Throws:
StarIOPortException - when a communication failure occurs

readPort

public int readPort(byte[] readBuffer,
                    int offset,
                    int size)
             throws StarIOPortException
This method reads data from the device.

Parameters:
offset - specifies where to begin writing data into the readBuffer - zero-based offset
size - number of bytes to read
Returns:
The number of bytes that were actually read. Under some interface types, this function will succeed even when no data was read in. Your application should call this function a limited number of times until the expected data has been read in or until an application determined retry threshold has been reached.
Throws:
StarIOPortException - when a communication failure occurs

retreiveStatus

public StarPrinterStatus retreiveStatus()
                                 throws StarIOPortException
This method retreives the device's detailed status.

Returns:
StarPrinterStatus structure giving the current device status
Throws:
StarIOPortException - when a communication failure occurs

beginCheckedBlock

public StarPrinterStatus beginCheckedBlock()
                                    throws StarIOPortException
This method initiates a checked block printing operation and returns the device's detailed status.

Returns:
StarPrinterStatus structure giving the current device status - don't bother printing if the printer is offline
Throws:
StarIOPortException - when a communication failure occurs

endCheckedBlock

public StarPrinterStatus endCheckedBlock()
                                  throws StarIOPortException
This method ends a checked block printing operation and returns the device's detailed status. This function does not return until either the printer has successfully printed all data or has gone offline in error. If the StarPrinterStatus structure indicates that the printer is online upon return than all data was successfully printed.

Returns:
StarPrinterStatus structure giving the current device status - if it's offline then printing failed
Throws:
StarIOPortException - when a communication failure occurs

resetDevice

public void resetDevice()
                 throws StarIOPortException
This method resets the device at the hardware level.

Throws:
StarIOPortException - when a communication failure occurs

finalize

protected void finalize()
                 throws java.lang.Throwable
Throws:
java.lang.Throwable