jdk.dio.generic.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 devices using generic I/O operations.
*
* The generic device API allows for accessing devices when there are no more specific
* standard Java API such as {@link jdk.dio.i2cbus.I2CDevice},
* {@link jdk.dio.spibus.SPIDevice}, {@link jdk.dio.gpio.GPIOPin} or
* {@link jdk.dio.gpio.GPIOPort}...
*
* This API offers 2 main interfaces:
*
*
* - {@link jdk.dio.generic.GenericDevice}
* - Device control operations and event listener registration. A device may implements this sole
* interface if it does not support any read and write operations.
* - {@link jdk.dio.generic.GenericBufferIODevice}
* - Device control operations and event listener registration as inherited from
* {@code GenericDevice} and byte buffer read and write
* operations.
*
*
*
* In order to access a device using its generic interface, an application should first open and
* obtain a {@code GenericDevice} instance for the device using its
* numeric ID, name, type (interface) and/or properties:
*
* - Using its ID
*
*
* GenericDevice device = (GenericDevice) DeviceManager.open(17);
*
*
- Using its name and interface
*
*
* GeneriBufferIODevice device = DeviceManager.open("STORAGE", GeneriBufferIODevice.class, null);
*
*
*
* Once the device opened, the application can set and get controls, read and write data using
* methods of the {@code GenericDevice} or
* {@code GenericBufferIODevice} interfaces.
*
*
* device.read(buffer, 0, buffer.length);
*
*
*
* When done, the application should call the
* {@link jdk.dio.generic.GenericDevice#close GenericDevice.close} method to close
* the Generic device.
*
*
* device.close();
*
*
*
* The following sample code gives an example of using the Generic API to access
* a Real Time Clock device:
*
*
* public static final int EVT_ALARM = 0;
* public static final GenericDeviceControl<Byte> SECONDS = new GenericDeviceControl<>(0, Byte.class);
* public static final GenericDeviceControl<Byte> SEC_ALARM = new GenericDeviceControl<>(1, Byte.class);
* public static final GenericDeviceControl<Byte> MINUTES = new GenericDeviceControl<>(2, Byte.class);
* public static final GenericDeviceControl<Byte> MIN_ALARM = new GenericDeviceControl<>(3, Byte.class);
* public static final GenericDeviceControl<Byte> HR_ALARM = new GenericDeviceControl<>(4, Byte.class);
* public static final GenericDeviceControl<Byte> HOURS = new GenericDeviceControl<>(5, Byte.class);
* public static final GenericDeviceControl<Boolean> ALARM_ENABLED = new GenericDeviceControl<>(6, Boolean.class);
*
* // Sets the daily alarm for after some delay
* public void setAlarm(byte delaySeconds, byte delayMinutes, byte delayHours) throws IOException, DeviceException {
* try (GenericDevice rtc = DeviceManager.open("RTC", GenericDevice.class, (String) null)) {
* byte currentSeconds = rtc.getControl(SECONDS);
* byte currentMinutes = rtc.getControl(MINUTES);
* byte currentHours = rtc.getControl(HOURS);
* byte i = (byte) ((currentSeconds + delaySeconds) % 60);
* byte j = (byte) ((currentSeconds + delaySeconds) / 60);
* rtc.setControl(SEC_ALARM, i);
* i = (byte) ((currentMinutes + delayMinutes + j) % 60);
* j = (byte) ((currentMinutes + delayMinutes + j) / 60);
* rtc.setControl(MIN_ALARM, i);
* i = (byte) ((currentHours + delayHours + j) % 24);
* rtc.setControl(HR_ALARM, i);
*
* rtc.setEventListener(EVT_ALARM, new GenericEventListener() {
*
* public void eventDispatched(GenericEvent event) {
* GenericDevice rtc = event.getDevice();
* // Notify application of alarm
* }
* });
* // Enable alarm.
* rtc.setControl(ALARM_ENABLED, true);
* }
* }
*
*
* The following sample code gives an example of using the Generic API to control
* and capture audio input from a microphone such a USB microphone exposed as a {@code GenericDevice}:
*
*
* public static final int EVT_VOLUME_CHANGED = 0;
* public static final GenericDeviceControl<Float> MIC_VOLUME = new GenericDeviceControl<>(0, Float.class);
* public static final GenericDeviceControl<Float> MIC_SAMPLE_RATE = new GenericDeviceControl<>(1, Float.class);
* public static final GenericDeviceControl<Boolean> MIC_AUTOMATIC_GAIN = new GenericDeviceControl<>(2, Boolean.class);
* public static final GenericDeviceControl<Boolean> MIC_MUTE = new GenericDeviceControl<>(3, Boolean.class);
*
* public void audioCapture(ByteBuffer buffer, float sampleRate, boolean agc) throws IOException, DeviceException {
* try (GenericBufferIODevice mic = DeviceManager.open("MICROPHONE", GenericBufferIODevice.class, (String) null)) {
* mic.setControl(MIC_SAMPLE_RATE, sampleRate);
* mic.setControl(MIC_AUTOMATIC_GAIN, agc);
* mic.setControl(MIC_MUTE, false);
*
* mic.setEventListener(EVT_VOLUME_CHANGED, new GenericEventListener() {
*
* public void eventDispatched(GenericEvent event) {
* GenericDevice mic = event.getDevice();
* try {
* float currentVolume = mic.getControl(MIC_VOLUME);
* // ...
* } catch (ClosedDeviceException ex) {
* ex.printStackTrace();
* } catch (IOException ex) {
* ex.printStackTrace();
* }
* }
* });
* mic.read(buffer);
* }
* }
*
*
*
* The preceding examples are using a try-with-resources statement;
* the {@link jdk.dio.generic.GenericDevice#close GenericDevice.close}
* method is 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.
*
*
* @since 1.0
*/
package jdk.dio.generic;