/*
* @(#)CommConnection.java 1.16 02/09/06 @(#)
*
* Copyright (c) 2001-2002 Sun Microsystems, Inc. All rights reserved.
* PROPRIETARY/CONFIDENTIAL
* Use is subject to license terms.
*/
package javax.microedition.io;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
/**
* This interface defines a logical serial port connection.
* A "logical" serial port is defined as a logical connection through
* which bytes are transferring serially. The logical serial port
* is defined within the underlying operating system and may not
* necessarily correspond to a physical RS-232 serial port. For
* instance, IrDA IRCOMM ports can commonly be configured as a logical serial
* port within the operating system so that it can act as a "logical"
* serial port.
* <P>
* A comm port is accessed using a Generic Connection Framework string
* with an explicit port identifier and embedded configuration
* parameters, each separated with a semi-colon (;).
* </P>
* <P>
* Only one application may be connected to a particular serial port at a
* given time.
* An <code>java.io.IOException</code> is thrown, if an attempt is
* made to open the serial port with <code>Connector.open()</code>
* and the connection is already open.
* </P>
* <P>
* A URI with the type and parameters is used to open the connection.
* The scheme (defined in RFC 2396) must be:<BR>
* <code>comm:<port identifier>[<optional parameters>]</code>
* </P>
* <P>
* The first parameter must be a port identifier, which is a
* logical device name.
* These identifiers are most likely device specific and should
* be used with care.
* </P>
* <P>
* The valid identifiers for a particular device and OS can be queried through
* the method <code>System.getProperty()</code> using the key
* <em>"microedition.commports"</em>. A comma separated list of ports
* is returned which can be combined with a <code>comm:</code> prefix
* as the URL string to be used to open a serial port connection.
* (See port naming convention below.)
* </P>
* <P>
* Any additional parameters must be separated by a semi-colon (;) and
* spaces are not allowed in the string. If a particular optional parameter
* is not applicable to a particular port, the parameter MAY be ignored.
* The port identifier MUST NOT contain a semi-colon (;).
* </P>
* <P>
* Legal parameters are defined by the definition of the parameters below.
* Illegal or unrecognized parameters cause an <code>IllegalArgumentException</code>.
* If the value of a parameter is supported by the device,
* it must be honored. If the value of a parameter is not supported
* a <code>java.io.IOException</code> is thrown.
* If a <code>baudrate</code> parameter is requested, it is treated
* in the same way that the <code>setBaudRate</code> method
* handles baudrates. e.g., if the baudrate requested is not
* supported the system MAY substitute a valid baudrate, which
* can be discovered using the <code>getBaudRate</code> method.
* </P>
* <H2>
* Optional Parameters
* </H2>
* <P>
* <TABLE BORDER="1">
* <TR> <TH> Parameter</TH>
* <TH>Default</TH>
* <TH>Description</TH>
* </TR>
* <TR>
* <TD><code>baudrate</code></TD>
* <TD><code>platform dependent</code></TD>
* <TD>The speed of the port.</TD>
* </TR>
* <TR>
* <TD><code>bitsperchar</code></TD>
* <TD><code>8</code></TD>
* <TD>The number bits per character(<code>7</code> or <code>8</code>).</TD>
* </TR>
* <TR>
* <TD><code>stopbits</code></TD>
* <TD><code>1</code></TD>
* <TD>The number of stop bits per char(<code>1</code> or <code>2</code>)</TD>
* </TR>
* <TR>
* <TD><code>parity</code></TD>
* <TD><code>none</code></TD>
* <TD>The parity can be <code>odd</code>, <code>even</code>,
* or <code>none</code>.</TD>
* </TR>
* <TR>
* <TD><code>blocking</code></TD>
* <TD><code>on</code></TD>
* <TD>If <code>on</code>, wait for a full buffer when reading.</TD>
* </TR>
* <TR>
* <TD><code>autocts</code></TD>
* <TD><code>on</code></TD>
* <TD>If <code>on</code>, wait for the CTS line to be on
* before writing. </TD>
* </TR>
* <TR>
* <TD><code>autorts</code></TD>
* <TD><code>on</code></TD>
* <TD>If <code>on</code>, turn on the RTS line when the
* input buffer is not full. If <code>off</code>,
* the RTS line is always on.</TD>
* </TR>
* </TABLE>
* <H2>
* BNF Format for Connector.open() string
* </H2>
* <P>
* The URI must conform to the BNF syntax specified below. If the URI
* does not conform to this syntax, an <code>IllegalArgumentException</code>
* is thrown.
* </P>
* <TABLE BORDER="1">
* <TR>
* <TD><comm_connection_string> </TD>
* <TD>::= "<strong>comm:</strong>"<port_id>[<options_list>] ; </TD>
* </TR>
* <TR>
* <TD><port_id> </TD>
* <TD>::= <I>string of alphanumeric characters</I> </TD>
* </TR>
* <TR>
* <TD><options_list> </TD>
* <TD>::= *(<baud_rate_string>| <bitsperchar>|
* <stopbits>| <parity>|
* <blocking>| <autocts>|
* <autorts>) ;
* <BR>; if an option duplicates a previous option in the
* <BR>; option list, that option overrides the previous
* <BR>; option</TD>
* </TR>
*
* <TR>
* <TD><baud_rate_string> </TD>
* <TD>::= "<strong>;baudrate=</strong>"<baud_rate> </TD>
* </TR>
* <TR>
* <TD><baud_rate> </TD>
* <TD>::= <I>string of digits</I> </TD>
* </TR>
* <TR>
* <TD><bitsperchar> </TD>
* <TD>::= "<strong>;bitsperchar=</strong>"<bit_value> </TD>
* </TR>
* <TR>
* <TD><bit_value> </TD>
* <TD>::= "7" | "8" </TD>
* </TR>
* <TR>
* <TD><stopbits> </TD>
* <TD>::= "<strong>;stopbits=</strong>"<stop_value> </TD>
* </TR>
* <TR>
* <TD><stop_value> </TD>
* <TD>::= "1" | "2" </TD>
* </TR>
* <TR>
* <TD><parity> </TD>
* <TD>::= "<strong>;parity=</strong>"<parity_value> </TD>
* </TR>
* <TR>
* <TD><parity_value> </TD>
* <TD>::= "even" | "odd" | "none" </TD>
* </TR>
* <TR>
* <TD><blocking> </TD>
* <TD>::= "<strong>;blocking=</strong>"<on_off> </TD>
* </TR>
* <TR>
* <TD><autocts> </TD>
* <TD>::= "<strong>;autocts=</strong>"<on_off> </TD>
* </TR>
* <TR>
* <TD><autorts> </TD>
* <TD>::= "<strong>;autorts=</strong>"<on_off> </TD>
* </TR>
* <TR>
* <TD><on_off> </TD>
* <TD>::= "on" | "off" </TD>
* </TR>
*</TABLE>
* <H2>
* Security
* </H2>
* <P>
* Access to serial ports is restricted to prevent unauthorized
* transmission or reception of data. The security model applied to
* the serial port connection is defined in the implementing profile.
* The security model may be applied on the invocation of the
* <code>Connector.open()</code>
* method with a valid serial port connection string.
* Should the application
* not be granted access to the serial port through the profile
* authorization scheme, a
* <code>java.lang.SecurityException</code> will be thrown from the
* <code>Connector.open()</code> method.
* The security model MAY also be applied during execution, specifically
* when the methods
* <code>openInputStream()</code>, <code>openDataInputStream()</code>,
* <code>openOutputStream()</code>, and
* <code>openDataOutputStream()</code> are invoked.
* </P>
* <H2>
* Examples
* </H2>
* <P>
* The following example shows how a <code>CommConnection</code>
* would be used to access a simple loopback program.
* </P>
* <PRE>
* CommConnection cc = (CommConnection)
* Connector.open("comm:com0;baudrate=19200");
* int baudrate = cc.getBaudRate();
* InputStream is = cc.openInputStream();
* OutputStream os = cc.openOutputStream();
* int ch = 0;
* while(ch != 'Z') {
* os.write(ch);
* ch = is.read();
* ch++;
* }
* is.close();
* os.close();
* cc.close();
* </PRE>
* <P>
* The following example shows how a <code>CommConnection</code>
* would be used to discover available comm ports.
* </P>
* <PRE>
* String port1;
* String ports = System.getProperty("microedition.commports");
* int comma = ports.indexOf(',');
* if (comma > 0) {
* // Parse the first port from the available ports list.
* port1 = ports.substring(0, comma);
* } else {
* // Only one serial port available.
* port1 =ports;
* }
* </PRE>
* <H2>Recommended Port Naming Convention</H2>
* <P>
* Logical port names can be defined to match platform naming conventions
* using any combination of alphanumeric characters. However, it is
* recommended that ports be named consistently among the implementations
* of this class according to a proposed convention. VM implementations
* should follow the following convention:<BR>
* Port names contain a text abbreviation indicating port capabilities followed
* by a sequential number for the port. The following device name types should
* be used:
* </P>
* <UL>
* <LI>COM#, where COM is for RS-232 ports and # is a number assigned
* to the port</LI>
* <LI>IR#, where IR is for IrDA IRCOMM ports and # is a number assigned to
* the port </LI>
* </UL>
* <P>
* This naming scheme allows API users to generally determine the type of port
* that they would like to use. For instance, if a application desires to
* "beam" a piece of data, the app could look for "IR#" ports for opening
* the connection.
* The alternative is a trial and error approach with all available ports.
* </P>
* @since MIDP 2.0
*/
public interface CommConnection
extends StreamConnection {
/**
* Gets the baudrate for the serial port connection.
* @return the baudrate of the connection
* @see #setBaudRate
*/
public int getBaudRate();
/**
* Sets the baudrate for the serial port connection.
* If the requested <code>baudrate</code> is not supported
* on the platform, then the system MAY use an alternate valid setting.
* The alternate value can be accessed using the
* <code>getBaudRate</code> method.
* @param baudrate the baudrate for the connection
* @return the previous baudrate of the connection
* @see #getBaudRate
*/
public int setBaudRate(int baudrate);
}
|
