javax.microedition.io.CommConnection Maven / Gradle / Ivy
/*
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2007 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below. For
example, no permission is given for you to incorporate this file, in
whole or in part, in an implementation of a Java specification.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative, as opposed to normative, use. The file and any
files generated from it may be used to generate other informative
documentation, such as a unified set of documents of API signatures for
a platform that includes technologies expressed as Java APIs. The file
may also be used to produce "compilation stubs," which allow
applications to be compiled and validated for such platforms.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 219: Foundation
Profile 1.1. In the event of a discrepency between this work and the
JSR 219 specification, which is available at
http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence.
*/
package javax.microedition.io;
import java.io.IOException;
/**
* 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.
*
* 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 (;).
*
*
* Only one application may be connected to a particular serial port at a
* given time.
* An java.io.IOException is thrown, if an attempt is
* made to open the serial port with Connector.open()
* and the connection is already open.
*
*
* A URI with the type and parameters is used to open the connection.
* The scheme (defined in RFC 2396) must be:
* comm:<port identifier>[<optional parameters>]
*
*
* 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.
*
*
* The valid identifiers for a particular device and OS can be queried through
* the method System.getProperty() using the key
* "microedition.commports". A comma separated list of ports
* is returned which can be combined with a comm: prefix
* as the URL string to be used to open a serial port connection.
* (See port naming convention below.)
*
*
* 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 (;).
*
*
* Legal parameters are defined by the definition of the parameters below.
* Illegal or unrecognized parameters cause an IllegalArgumentException.
* 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 java.io.IOException is thrown.
* If a baudrate parameter is requested, it is treated
* in the same way that the setBaudRate 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 getBaudRate method.
*
*
* Optional Parameters
*
*
*
* Parameter
* Default
* Description
*
*
* baudrateplatform dependentThe speed of the port.
*
*
* bitsperchar8The number bits per character(7 or 8).
*
*
* stopbits1The number of stop bits per char(1 or 2)
*
*
* paritynoneThe parity can be odd, even,
* or none.
*
*
* blockingonIf on, wait for a full buffer when reading.
*
*
* autoctsonIf on, wait for the CTS line to be on
* before writing.
*
*
* autortsonIf on, turn on the RTS line when the
* input buffer is not full. If off,
* the RTS line is always on.
*
*
*
* BNF Format for Connector.open() string
*
*
* The URI must conform to the BNF syntax specified below. If the URI
* does not conform to this syntax, an IllegalArgumentException
* is thrown.
*
*
*
* <comm_connection_string>
* ::= "comm:"<port_id>[<options_list>] ;
*
*
* <port_id>
* ::= string of alphanumeric characters
*
*
* <options_list>
* ::= *(<baud_rate_string>| <bitsperchar>|
* <stopbits>| <parity>|
* <blocking>| <autocts>|
* <autorts>) ;
*
; if an option duplicates a previous option in the
*
; option list, that option overrides the previous
*
; option
*
*
*
* <baud_rate_string>
* ::= ";baudrate="<baud_rate>
*
*
* <baud_rate>
* ::= string of digits
*
*
* <bitsperchar>
* ::= ";bitsperchar="<bit_value>
*
*
* <bit_value>
* ::= "7" | "8"
*
*
* <stopbits>
* ::= ";stopbits="<stop_value>
*
*
* <stop_value>
* ::= "1" | "2"
*
*
* <parity>
* ::= ";parity="<parity_value>
*
*
* <parity_value>
* ::= "even" | "odd" | "none"
*
*
* <blocking>
* ::= ";blocking="<on_off>
*
*
* <autocts>
* ::= ";autocts="<on_off>
*
*
* <autorts>
* ::= ";autorts="<on_off>
*
*
* <on_off>
* ::= "on" | "off"
*
*
*
* Security
*
*
* 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
* Connector.open()
* 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
* java.lang.SecurityException will be thrown from the
* Connector.open() method.
* The security model MAY also be applied during execution, specifically
* when the methods
* openInputStream(), openDataInputStream(),
* openOutputStream(), and
* openDataOutputStream() are invoked.
*
*
* Examples
*
*
* The following example shows how a CommConnection
* would be used to access a simple loopback program.
*
*
* 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();
*
*
* The following example shows how a CommConnection
* would be used to discover available comm ports.
*
*
* 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;
* }
*
* Recommended Port Naming Convention
*
* 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:
* 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:
*
*
* - COM#, where COM is for RS-232 ports and # is a number assigned
* to the port
* - IR#, where IR is for IrDA IRCOMM ports and # is a number assigned to
* the port
*
*
* 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.
*
* @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 baudrate is not supported
* on the platform, then the system MAY use an alternate valid setting.
* The alternate value can be accessed using the
* getBaudRate method.
* @param baudrate the baudrate for the connection
* @return the previous baudrate of the connection
* @see #getBaudRate
*/
public int setBaudRate(int baudrate);
}