001package com.pi4j.io.serial;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  SerialDataReader.java
009 *
010 * This file is part of the Pi4J project. More information about
011 * this project can be found here:  https://www.pi4j.com/
012 * **********************************************************************
013 * %%
014 * Copyright (C) 2012 - 2019 Pi4J
015 * %%
016 * This program is free software: you can redistribute it and/or modify
017 * it under the terms of the GNU Lesser General Public License as
018 * published by the Free Software Foundation, either version 3 of the
019 * License, or (at your option) any later version.
020 *
021 * This program is distributed in the hope that it will be useful,
022 * but WITHOUT ANY WARRANTY; without even the implied warranty of
023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
024 * GNU General Lesser Public License for more details.
025 *
026 * You should have received a copy of the GNU General Lesser Public
027 * License along with this program.  If not, see
028 * <http://www.gnu.org/licenses/lgpl-3.0.html>.
029 * #L%
030 */
031
032import java.io.IOException;
033import java.io.OutputStream;
034import java.io.Writer;
035import java.nio.ByteBuffer;
036import java.nio.CharBuffer;
037import java.nio.charset.Charset;
038import java.util.Collection;
039
040
041public interface SerialDataReader {
042
043    /**
044     * Gets the number of bytes available for reading, or -1 for any error condition.
045     *
046     * @return Returns the number of bytes available for reading, or -1 for any error
047     */
048    public int available() throws IllegalStateException, IOException;
049
050
051    // ----------------------------------------
052    // READ OPERATIONS
053    // ----------------------------------------
054
055    /**
056     * <p>discard/drain all available bytes from the serial port/device.</p>
057     */
058    public void discardData() throws IllegalStateException, IOException;
059
060    /**
061     * <p>Reads all available bytes from the serial port/device.</p>
062     *
063     * @return Returns a byte array with the data read from the serial port.
064     */
065    public byte[] read() throws IllegalStateException, IOException;
066
067    /**
068     * <p>Reads a length of bytes from the port/serial device.</p>
069     *
070     * @param length
071     *          The number of bytes to get from the serial port/device.
072     *          This number must not be higher than the number of available bytes.
073     *
074     * @return Returns a byte array with the data read from the serial port.
075     */
076    public byte[] read(int length) throws IllegalStateException, IOException;
077
078    /**
079     * <p>Reads all available bytes from the serial device into a provided ByteBuffer.</p>
080     *
081     * @param buffer
082     *          The ByteBuffer object to write to.
083     */
084    public void read(ByteBuffer buffer) throws IllegalStateException, IOException;
085
086    /**
087     * <p>Reads a length bytes from the serial port/device into a provided ByteBuffer.</p>
088     *
089     * @param length
090     *          The number of bytes to get from the serial port/device.
091     *          This number must not be higher than the number of available bytes.
092     * @param buffer
093     *          The ByteBuffer object to write to.
094     *
095     */
096    public void read(int length, ByteBuffer buffer) throws IllegalStateException, IOException;
097
098    /**
099     * <p>Reads all available bytes from the serial device into a provided OutputStream.</p>
100     *
101     * @param stream
102     *          The OutputStream object to write to.
103     */
104    public void read(OutputStream stream) throws IllegalStateException, IOException;
105    /**
106     * <p>Reads a length bytes from the serial port/device into a provided OutputStream.</p>
107     *
108     * @param length
109     *          The number of bytes to get from the serial port/device.
110     *          This number must not be higher than the number of available bytes.
111     * @param stream
112     *          The OutputStream object to write to.
113     *
114     */
115    public void read(int length, OutputStream stream) throws IllegalStateException, IOException;
116
117    /**
118     * <p>Reads all available bytes from the serial port/device into a provided collection of ByteBuffer objects.</p>
119     *
120     * @param collection
121     *          The collection of CharSequence objects to append to.
122     *
123     */
124    public void read(Collection<ByteBuffer> collection) throws IllegalStateException, IOException;
125
126    /**
127     * <p>Reads a length of bytes from the serial port/device into a provided collection of ByteBuffer objects.</p>
128     *
129     * @param length
130     *          The number of bytes to get from the serial port/device.
131     *          This number must not be higher than the number of available bytes.
132     * @param collection
133     *          The collection of CharSequence objects to append to.
134     *
135     */
136    public void read(int length, Collection<ByteBuffer> collection) throws IllegalStateException, IOException;
137
138    /**
139     * <p>Reads all available bytes from the port/serial device and returns a CharBuffer from the decoded bytes.</p>
140     *
141     * @param charset
142     *          The character set to use for encoding/decoding bytes to/from text characters
143     *
144     * @return Returns a character set with the data read from the serial port.
145     */
146    public CharBuffer read(Charset charset) throws IllegalStateException, IOException;
147
148    /**
149     * <p>Reads a length of bytes from the port/serial device and returns a CharBuffer from the decoded bytes.</p>
150     *
151     * @param length
152     *          The number of bytes to get from the serial port/device.
153     *          This number must not be higher than the number of available bytes.
154     * @param charset
155     *          The character set to use for encoding/decoding bytes to/from text characters
156     *
157     * @return Returns a character set with the data read from the serial port.
158     */
159    public CharBuffer read(int length, Charset charset) throws IllegalStateException, IOException;
160
161    /**
162     * <p>Reads all available bytes from the serial port/device into a provided Writer.</p>
163     *
164     * @param charset
165     *          The character set to use for encoding/decoding bytes to/from text characters
166     * @param writer
167     *          The Writer object to write to.
168     *
169     */
170    public void read(Charset charset, Writer writer) throws IllegalStateException, IOException;
171
172    /**
173     * <p>Reads a length bytes from the serial port/device into a provided Writer.</p>
174     *
175     * @param length
176     *          The number of bytes to get from the serial port/device.
177     *          This number must not be higher than the number of available bytes.
178     * @param charset
179     *          The character set to use for encoding/decoding bytes to/from text characters
180     * @param writer
181     *          The Writer object to write to.
182     *
183     */
184    public void read(int length, Charset charset, Writer writer) throws IllegalStateException, IOException;
185}