001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.io;
028:
029: import java.io.IOException;
030: import java.io.InputStream;
031: import java.io.OutputStream;
032:
033: /**
034: * This interface defines a logical serial port connection.
035: * A "logical" serial port is defined as a logical connection through
036: * which bytes are transferring serially. The logical serial port
037: * is defined within the underlying operating system and may not
038: * necessarily correspond to a physical RS-232 serial port. For
039: * instance, IrDA IRCOMM ports can commonly be configured as a logical serial
040: * port within the operating system so that it can act as a "logical"
041: * serial port.
042: * <P>
043: * A comm port is accessed using a Generic Connection Framework string
044: * with an explicit port identifier and embedded configuration
045: * parameters, each separated with a semi-colon (;).
046: * </P>
047: * <P>
048: * Only one application may be connected to a particular serial port at a
049: * given time.
050: * An <code>java.io.IOException</code> is thrown, if an attempt is
051: * made to open the serial port with <code>Connector.open()</code>
052: * and the connection is already open.
053: * </P>
054: * <P>
055: * A URI with the type and parameters is used to open the connection.
056: * The scheme (defined in RFC 2396) must be:<BR>
057: * <code>comm:<port identifier>[<optional parameters>]</code>
058: * </P>
059: * <P>
060: * The first parameter must be a port identifier, which is a
061: * logical device name.
062: * These identifiers are most likely device specific and should
063: * be used with care.
064: * </P>
065: * <P>
066: * The valid identifiers for a particular device and OS can be queried through
067: * the method <code>System.getProperty()</code> using the key
068: * <em>"microedition.commports"</em>. A comma separated list of ports
069: * is returned which can be combined with a <code>comm:</code> prefix
070: * as the URL string to be used to open a serial port connection.
071: * (See port naming convention below.)
072: * </P>
073: * <P>
074: * Any additional parameters must be separated by a semi-colon (;) and
075: * spaces are not allowed in the string. If a particular optional parameter
076: * is not applicable to a particular port, the parameter MAY be ignored.
077: * The port identifier MUST NOT contain a semi-colon (;).
078: * </P>
079: * <P>
080: * Legal parameters are defined by the definition of the parameters below.
081: * Illegal or unrecognized parameters cause an
082: * <code>IllegalArgumentException</code>.
083: * If the value of a parameter is supported by the device,
084: * it must be honored. If the value of a parameter is not supported
085: * a <code>java.io.IOException</code> is thrown.
086: * If a <code>baudrate</code> parameter is requested, it is treated
087: * in the same way that the <code>setBaudRate</code> method
088: * handles baudrates. e.g., if the baudrate requested is not
089: * supported the system MAY substitute a valid baudrate, which
090: * can be discovered using the <code>getBaudRate</code> method.
091: * </P>
092: * <H2>
093: * Optional Parameters
094: * </H2>
095: * <P>
096: * <TABLE BORDER="1">
097: * <TR> <TH> Parameter</TH>
098: * <TH>Default</TH>
099: * <TH>Description</TH>
100: * </TR>
101: * <TR>
102: * <TD><code>baudrate</code></TD>
103: * <TD><code>platform dependent</code></TD>
104: * <TD>The speed of the port.</TD>
105: * </TR>
106: * <TR>
107: * <TD><code>bitsperchar</code></TD>
108: * <TD><code>8</code></TD>
109: * <TD>The number bits per character(<code>7</code> or <code>8</code>).</TD>
110: * </TR>
111: * <TR>
112: * <TD><code>stopbits</code></TD>
113: * <TD><code>1</code></TD>
114: * <TD>The number of stop bits per char(<code>1</code> or <code>2</code>)</TD>
115: * </TR>
116: * <TR>
117: * <TD><code>parity</code></TD>
118: * <TD><code>none</code></TD>
119: * <TD>The parity can be <code>odd</code>, <code>even</code>,
120: * or <code>none</code>.</TD>
121: * </TR>
122: * <TR>
123: * <TD><code>blocking</code></TD>
124: * <TD><code>on</code></TD>
125: * <TD>If <code>on</code>, wait for a full buffer when reading.</TD>
126: * </TR>
127: * <TR>
128: * <TD><code>autocts</code></TD>
129: * <TD><code>on</code></TD>
130: * <TD>If <code>on</code>, wait for the CTS line to be on
131: * before writing. </TD>
132: * </TR>
133: * <TR>
134: * <TD><code>autorts</code></TD>
135: * <TD><code>on</code></TD>
136: * <TD>If <code>on</code>, turn on the RTS line when the
137: * input buffer is not full. If <code>off</code>,
138: * the RTS line is always on.</TD>
139: * </TR>
140: * </TABLE>
141: * <H2>
142: * BNF Format for Connector.open() string
143: * </H2>
144: * <P>
145: * The URI must conform to the BNF syntax specified below. If the URI
146: * does not conform to this syntax, an <code>IllegalArgumentException</code>
147: * is thrown.
148: * </P>
149: * <TABLE BORDER="1">
150: * <TR>
151: * <TD><comm_connection_string> </TD>
152: * <TD>::= "<strong>comm:</strong>"<port_id>[<options_list>] ; </TD>
153: * </TR>
154: * <TR>
155: * <TD><port_id> </TD>
156: * <TD>::= <I>string of alphanumeric characters</I> </TD>
157: * </TR>
158: * <TR>
159: * <TD><options_list> </TD>
160: * <TD>::= *(<baud_rate_string>| <bitsperchar>|
161: * <stopbits>| <parity>|
162: * <blocking>| <autocts>|
163: * <autorts>) ;
164: * <BR>; if an option duplicates a previous option in the
165: * <BR>; option list, that option overrides the previous
166: * <BR>; option</TD>
167: * </TR>
168: *
169: * <TR>
170: * <TD><baud_rate_string> </TD>
171: * <TD>::= "<strong>;baudrate=</strong>"<baud_rate> </TD>
172: * </TR>
173: * <TR>
174: * <TD><baud_rate> </TD>
175: * <TD>::= <I>string of digits</I> </TD>
176: * </TR>
177: * <TR>
178: * <TD><bitsperchar> </TD>
179: * <TD>::= "<strong>;bitsperchar=</strong>"<bit_value> </TD>
180: * </TR>
181: * <TR>
182: * <TD><bit_value> </TD>
183: * <TD>::= "7" | "8" </TD>
184: * </TR>
185: * <TR>
186: * <TD><stopbits> </TD>
187: * <TD>::= "<strong>;stopbits=</strong>"<stop_value> </TD>
188: * </TR>
189: * <TR>
190: * <TD><stop_value> </TD>
191: * <TD>::= "1" | "2" </TD>
192: * </TR>
193: * <TR>
194: * <TD><parity> </TD>
195: * <TD>::= "<strong>;parity=</strong>"<parity_value> </TD>
196: * </TR>
197: * <TR>
198: * <TD><parity_value> </TD>
199: * <TD>::= "even" | "odd" | "none" </TD>
200: * </TR>
201: * <TR>
202: * <TD><blocking> </TD>
203: * <TD>::= "<strong>;blocking=</strong>"<on_off> </TD>
204: * </TR>
205: * <TR>
206: * <TD><autocts> </TD>
207: * <TD>::= "<strong>;autocts=</strong>"<on_off> </TD>
208: * </TR>
209: * <TR>
210: * <TD><autorts> </TD>
211: * <TD>::= "<strong>;autorts=</strong>"<on_off> </TD>
212: * </TR>
213: * <TR>
214: * <TD><on_off> </TD>
215: * <TD>::= "on" | "off" </TD>
216: * </TR>
217: *</TABLE>
218: * <H2>
219: * Security
220: * </H2>
221: * <P>
222: * Access to serial ports is restricted to prevent unauthorized
223: * transmission or reception of data. The security model applied to
224: * the serial port connection is defined in the implementing profile.
225: * The security model may be applied on the invocation of the
226: * <code>Connector.open()</code>
227: * method with a valid serial port connection string.
228: * Should the application
229: * not be granted access to the serial port through the profile
230: * authorization scheme, a
231: * <code>java.lang.SecurityException</code> will be thrown from the
232: * <code>Connector.open()</code> method.
233: * The security model MAY also be applied during execution, specifically
234: * when the methods
235: * <code>openInputStream()</code>, <code>openDataInputStream()</code>,
236: * <code>openOutputStream()</code>, and
237: * <code>openDataOutputStream()</code> are invoked.
238: * </P>
239: * <H2>
240: * Examples
241: * </H2>
242: * <P>
243: * The following example shows how a <code>CommConnection</code>
244: * would be used to access a simple loopback program.
245: * </P>
246: * <PRE>
247: * CommConnection cc = (CommConnection)
248: * Connector.open("comm:com0;baudrate=19200");
249: * int baudrate = cc.getBaudRate();
250: * InputStream is = cc.openInputStream();
251: * OutputStream os = cc.openOutputStream();
252: * int ch = 0;
253: * while(ch != 'Z') {
254: * os.write(ch);
255: * ch = is.read();
256: * ch++;
257: * }
258: * is.close();
259: * os.close();
260: * cc.close();
261: * </PRE>
262: * <P>
263: * The following example shows how a <code>CommConnection</code>
264: * would be used to discover available comm ports.
265: * </P>
266: * <PRE>
267: * String port1;
268: * String ports = System.getProperty("microedition.commports");
269: * int comma = ports.indexOf(',');
270: * if (comma > 0) {
271: * // Parse the first port from the available ports list.
272: * port1 = ports.substring(0, comma);
273: * } else {
274: * // Only one serial port available.
275: * port1 =ports;
276: * }
277: * </PRE>
278: * <H2>Recommended Port Naming Convention</H2>
279: * <P>
280: * Logical port names can be defined to match platform naming conventions
281: * using any combination of alphanumeric characters. However, it is
282: * recommended that ports be named consistently among the implementations
283: * of this class according to a proposed convention. VM implementations
284: * should follow the following convention:<BR>
285: * Port names contain a text abbreviation indicating port capabilities followed
286: * by a sequential number for the port. The following device name types should
287: * be used:
288: * </P>
289: * <UL>
290: * <LI>COM#, where COM is for RS-232 ports and # is a number assigned
291: * to the port</LI>
292: * <LI>IR#, where IR is for IrDA IRCOMM ports and # is a number assigned to
293: * the port </LI>
294: * </UL>
295: * <P>
296: * This naming scheme allows API users to generally determine the type of port
297: * that they would like to use. For instance, if a application desires to
298: * "beam" a piece of data, the app could look for "IR#" ports for opening
299: * the connection.
300: * The alternative is a trial and error approach with all available ports.
301: * </P>
302: * @since MIDP 2.0
303: */
304:
305: public interface CommConnection extends StreamConnection {
306:
307: /**
308: * Gets the baudrate for the serial port connection.
309: * @return the baudrate of the connection
310: * @see #setBaudRate
311: */
312: public int getBaudRate();
313:
314: /**
315: * Sets the baudrate for the serial port connection.
316: * If the requested <code>baudrate</code> is not supported
317: * on the platform, then the system MAY use an alternate valid setting.
318: * The alternate value can be accessed using the
319: * <code>getBaudRate</code> method.
320: * @param baudrate the baudrate for the connection
321: * @return the previous baudrate of the connection
322: * @see #getBaudRate
323: */
324: public int setBaudRate(int baudrate);
325:
326: }
|