Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.io
Interface CommConnection

All Superinterfaces:
  Connection, InputConnection, OutputConnection, StreamConnection

All Known Subinterfaces:
  CommConnectionControlLines

public interface CommConnection
extends StreamConnection

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
--- | --- | ---
`baudrate` | `platform dependent` | The speed of the port.
`bitsperchar` | `8` | The number bits per character(`7` or `8`).
`stopbits` | `1` | The number of stop bits per char(`1` or `2`)
`parity` | `none` | The parity can be `odd`, `even`, or `none`.
`blocking` | `on` | If `on`, the reading on the stream will block until input data is available, the end of the stream is detected or an exception is thrown.
`autocts` | `on` | If `on`, wait for the CTS line to be on before writing.
`autorts` | `on` | If `on`, turn on the RTS line when the input buffer is not full. If `off`, the RTS line is always on.

[SIEMENS WM ]
The following restrictions apply:
`baudrate`: 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, 115200, 230400, 460800
`stopbits`: only 1 supported
`parity`: character format 7N1 not supported
`GPS0 port`: any baudrate accepted, autocts and autorts not used
For synchronization reasons the connector.open and the setBaudRate methods block until the send buffer (from module to external) is empty. When using System.out on the same port as CommConnection all outputs are discarded while waitung for the send buffer to become emtpy, in order to avoid deadlocks.

## 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.

[SIEMENS WM]

Some Siemens modules feature GPS onboard, this additional hardware is accessible with CommConnection. The logical port names is always GPS0:

- GPS#, where GPS is for the GPS-over-CommConnection port, # is always 0

Please note the SIEMENS WM restrictions for the Optional Parameter.

Since:
  MIDP 2.0

Method Summary
`int` | `getBaudRate()` Gets the baudrate for the serial port connection.
`int` | `setBaudRate(int baudrate)` Sets the baudrate for the serial port connection.

Methods inherited from interface javax.microedition.io.InputConnection
`openDataInputStream, openInputStream`

Methods inherited from interface javax.microedition.io.Connection
`close`

Methods inherited from interface javax.microedition.io.OutputConnection
`openDataOutputStream, openOutputStream`

Method Detail

### getBaudRate

    public int getBaudRate()

  Gets the baudrate for the serial port connection.

  Returns:
    the baudrate of the connection
  See Also:
    `setBaudRate(int)`

### setBaudRate

    public int setBaudRate(int baudrate)

  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.

  Parameters:
    `baudrate` - the baudrate for the connection
  Returns:
    the previous baudrate of the connection
  See Also:
    `getBaudRate()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 2.0 of IM Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.