MIDP Networking and Serial Communications

15.8 CommConnection

The CommConnection interface defines an API for a logical serial port connection. The CommConnection extends the StreamConnection interface, through which bytes are transferred using input and output streams. The underlying operating system defines the logical serial ports that can be used. Such a port does not need to correspond to a physical RS-232 serial port. For instance, IrDA IRCOMM ports are commonly configured as logical serial ports within the device.

An application opens a serial port by calling the Connector.open method. The application must provide a URI string that begins with "comm:" followed by a port identifier, followed optionally by a semicolon and a semicolon-separated list of parameter-value pairs. The name of a parameter is separated from its value with an equals sign (=). Spaces are not allowed in the string. For example, "comm:COM0;baudrate=19200" is a valid string.

The port identifier is a logical device name defined by the device. Port identifiers will probably be device-specific, so applications should use them with care. (See Section 15.8.3, "Recommended Convention for Naming Ports.") Applications can get a comma-separated list of valid port identifiers for a particular device and operating system by calling the System.getProperty method with the key microedition.commports.

Any additional parameters must be separated by a semicolon. If a particular optional parameter is not applicable to a particular port, the device is permitted to ignore it. Legal parameters are listed in Figure. If the application supplies an illegal or unrecognized parameter, the Connector.open method throws an IllegalArgumentException. If the device supports a parameter value, it must be honored. If the device does not support a parameter value, the Connector.open method throws a java.io.IOException. If an option duplicates a previous option, the last value overrides the previous value.

Only one application may be connected to a particular serial port at a given time. The Connector.open method throws a java.io.IOException if an application tries to open the serial port when the connection is already open.

1 Getting and Setting the Serial Port Speed

The application may need to know or set the baud rate (speed) of the serial port to communicate with an external device. There are two ways to set the baud rate. The application can set it in the Connector.open method by putting the optional parameter baudrate into the method's URI string argument. The application can also set the baud rate after the connection is open with the setBaudRate method. If the application does not set a value, the baud rate defaults to a device-specific default value. If the application requests a baud rate that the device does not support, the system may substitute a valid baud rate. The application determines the actual baud rate of the connection by calling the getBaudRate method.

15.8.2 Security for CommConnection

Access to serial ports is restricted to prevent unauthorized transmission or reception of data. MIDlet suites needing to use serial ports must request the javax.microedition.io.Connector.comm permission for Trusted MIDlet suites as described in Section 18.3, "Trusted MIDlet Suite Security Model."

The device may try to authorize the MIDlet when the MIDlet calls the Connector.open method with a valid serial port connection string. If the authorization fails and the MIDlet is not allowed to use the serial port connection API, the Connector.open method throws a java.lang.SecurityException. The device might also check the MIDlet's permission when the MIDlet calls the methods openInputStream, openDataInputStream, openOutputStream, or openDataOutputStream methods.

3 Recommended Convention for Naming Ports

A logical port name can use any combination of alphanumeric characters except a semicolon. Although logical port names can be defined to match a platform's naming conventions, implementations of the virtual machine should use the following convention: port names should 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 the API users to generally determine the type of port that they would like to use. For instance, if an application wants to beam a piece of data, the application could look for IR# ports for opening the connection. The alternative is a trial-and-error approach with all available ports.

4 Examples

This section provides two examples of serial port access using the CommConnection interface. The first example shows how a CommConnection would be used to access a simple program that echoes the characters it receives. The second example shows how to discover the serial ports available on the device and select the first available serial port.

The following example shows a program that echoes characters through a CommConnection.

// Open the CommConnection and its streams
CommConnection cc =
    (CommConnection)Connector.open("comm:com0;baudrate=19200");
int baudrate = cc.getBaudRate();
InputStream is = cc.openInputStream();
OutputStream os = cc.openOutputStream();

// Write characters and read them back in
int ch = 0;
while (ch != 'Z') {
    os.write(ch);
    ch = is.read();
    ch++;
}

// Close the connection and its streams
is.close();
os.close();
cc.close();

The following example shows how to discover the available serial ports on the device and select the first available serial port.

// Get the comma-separated list of 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;
}