jdk.dio.uart.package-info Maven / Gradle / Ivy
Show all versions of org.openjdk.dio Show documentation
/*
* Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* Interfaces and classes for controlling and reading and writing from/to Universal Asynchronous Receiver/Transmitter
* (UART), with optional Modem signals control.
*
* In order to access and control a specific UART device, an application should first open and obtain an
* {@link jdk.dio.uart.UART} instance for the UART device using its numeric ID, name, type (interface)
* and/or properties:
*
*
* - Using its ID
* -
*
*
* UART uart = (UART) DeviceManager.open(14);
*
*
*
* - Using its name and interface
* -
*
*
* UART uart = DeviceManager.open("HOST", UART.class, null);
*
*
Or (with modem signals control properties),
*
* ModemUART uart = DeviceManager.open("MODEM", ModemUART.class, null);
*
*
*
*
*
* Once opened, an application can read the received data bytes and write the data bytes to be transmitted through the
* UART using methods of the {@link java.nio.channels.ByteChannel ByteChannel} interface.
*
*
*
* ByteBuffer buffer = new ByteBuffer();
* ...
* uart.read(buffer);
* ...
* uart.write(buffer);
* ...
*
*
*
* When done, the application should call the {@link jdk.dio.uart.UART#close() } method to
* close the UART device.
*
*
* uart.close();
*
*
* The following sample code gives an example of using the UART API to communicate with some host
* terminal:
*
*
* try (UART host = DeviceManager.open("HOST", UART.class, (String) null);
* InputStream is = Channels.newInputStream(host);
* OutputStream os = Channels.newOutputStream(host)) {
* StringBuffer cmd = new StringBuffer();
* int c = 0;
* while (true) {
* os.write('$');
* os.write(' '); // echo prompt
* while (c != '\n' && c != '\003') { // echo input
* c = is.read();
* os.write(c);
* cmd.append(c);
* }
* if (c == '\003') { // CTL-C
* break;
* }
* process(cmd); // Process the command
* }
* } catch (IOException ioe) {
* // Handle exception
* }
*
*
* The following sample codes give examples of using the ModemUART API to additionally control the MODEM
* signals:
*
*
* try (ModemUART modem = DeviceManager.open("HOST", ModemUART.class, (String) null);
* InputStream is = Channels.newInputStream(modem);
* OutputStream os = Channels.newOutputStream(modem)) {
* modem.setSignalChangeListener(new ModemSignalListener<ModemUART>() {
*
* @Override
* public void signalStateChanged(ModemSignalEvent<ModemUART> event) {
* if (event.getSignalState() == false) {
* ModemUART modem = event.getDevice();
* // Process MODEM hang-up...
* }
* }
* }, ModemSignalsControl.DCD_SIGNAL);
* // Process input and output...
* } catch (IOException ioe) {
* // Handle exception
* }
*
*
The preceding example is using a try-with-resources statement; the
* {@link jdk.dio.uart.UART#close UART.close}, {@link java.io.InputStream#close
* InputStream.close} and {@link java.io.OutputStream#close OutputStream.close} methods are automatically invoked
* by the platform at the end of the statement.
*
* Unless otherwise noted, permission and security checks that may cause
* a {@link java.lang.SecurityException SecurityException} to be thrown must be performed
* in priority to any other checks or operations once performed the checking of the input parameters
* from which the permission target names and action lists are retrieved and assembled.
*
* Unless otherwise noted, passing a {@code null} argument to a constructor or method in any class
* or interface in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
*
* This package requires the {@link jdk.dio.modem} package.
*
*
* @since 1.0
*/
package jdk.dio.uart;