001package com.pi4j.io.serial;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  SerialDataWriter.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.InputStream;
034import java.nio.ByteBuffer;
035import java.nio.CharBuffer;
036import java.nio.charset.Charset;
037import java.util.Collection;
038
039public interface SerialDataWriter {
040
041
042    // ----------------------------------------
043    // WRITE OPERATIONS
044    // ----------------------------------------
045
046    /**
047     * <p>Sends an array of bytes to the serial port/device identified by the given file descriptor.</p>
048     *
049     * @param data
050     *            A ByteBuffer of data to be transmitted.
051     * @param offset
052     *            The starting index (inclusive) in the array to send from.
053     * @param length
054     *            The number of bytes from the byte array to transmit to the serial port.
055     */
056    public void write(byte[] data, int offset, int length) throws IllegalStateException, IOException;
057
058    /**
059     * <p>Sends one of more bytes to the serial device identified by the given file descriptor.</p>
060     *
061     * @param data
062     *            One or more bytes (or an array) of data to be transmitted. (variable-length-argument)
063     */
064    public void write(byte ... data) throws IllegalStateException, IOException;
065
066    /**
067     * <p>Sends one of more bytes arrays to the serial device identified by the given file descriptor.</p>
068     *
069     * @param data
070     *            One or more byte arrays of data to be transmitted. (variable-length-argument)
071     */
072    public void write(byte[] ... data) throws IllegalStateException, IOException;
073
074    /**
075     * Read the content of byte buffer and write the data to the serial port transmit buffer.
076     * (The buffer is read from the current position up to the 'limit' value, not the 'capacity'.  You may need to
077     * rewind() or flip() the byte buffer if you have just written to it.)
078     *
079     * @param data
080     *            A ByteBuffer of data to be transmitted.
081     */
082    public void write(ByteBuffer... data) throws IllegalStateException, IOException;
083
084    /**
085     * Read content from an input stream of data and write it to the serial port transmit buffer.
086     *
087     * @param input
088     *          An InputStream of data to be transmitted
089     */
090    public void write(InputStream input) throws IllegalStateException, IOException;
091    /**
092     * <p>Sends an array of characters to the serial port/device identified by the given file descriptor.</p>
093     *
094     * @param charset
095     *           The character set to use for encoding/decoding bytes to/from text characters
096     * @param data
097     *           An array of chars to be decoded into bytes and transmitted.
098     * @param offset
099     *           The starting index (inclusive) in the array to send from.
100     * @param length
101     *           The number of characters from the char array to transmit to the serial port.
102     */
103    public void write(Charset charset, char[] data, int offset, int length) throws IllegalStateException, IOException;
104
105    /**
106     * <p>Sends an array of characters to the serial port/device identified by the given file descriptor.</p>
107     *
108     * @param charset
109     *           The character set to use for encoding/decoding bytes to/from text characters
110     * @param data
111     *           One or more characters (or an array) of data to be transmitted. (variable-length-argument)
112     */
113    public void write(Charset charset, char ... data) throws IllegalStateException, IOException;
114
115    /**
116     * <p>Sends an array of ASCII characters to the serial port/device identified by the given file descriptor.</p>
117     *
118     * @param data
119     *           One or more ASCII characters (or an array) of data to be transmitted. (variable-length-argument)
120     */
121    public void write(char ... data) throws IllegalStateException, IOException;
122
123    /**
124     * <p>Sends one or more CharBuffers to the serial port/device identified by the given file descriptor.</p>
125     *
126     * @param charset
127     *           The character set to use for encoding/decoding bytes to/from text characters
128     * @param data
129     *           One or more CharBuffers (or an array) of data to be transmitted. (variable-length-argument)
130     */
131    public void write(Charset charset, CharBuffer... data) throws IllegalStateException, IOException;
132
133    /**
134     * <p>Sends one or more ASCII CharBuffers to the serial port/device identified by the given file descriptor.</p>
135     *
136     * @param data
137     *           One or more ASCII CharBuffers (or an array) of data to be transmitted. (variable-length-argument)
138     */
139    public void write(CharBuffer ... data) throws IllegalStateException, IOException;
140
141    /**
142     * <p>Sends one or more string objects to the serial port/device identified by the given file descriptor.</p>
143     *
144     * @param charset
145     *           The character set to use for encoding/decoding bytes to/from text characters
146     * @param data
147     *           One or more string objects (or an array) of data to be transmitted. (variable-length-argument)
148     */
149    public void write(Charset charset, CharSequence ... data) throws IllegalStateException, IOException;
150
151    /**
152     * <p>Sends one or more ASCII string objects to the serial port/device identified by the given file descriptor.</p>
153     *
154     * @param data
155     *           One or more ASCII string objects (or an array) of data to be transmitted. (variable-length-argument)
156     */
157    public void write(CharSequence ... data) throws IllegalStateException, IOException;
158
159    /**
160     * <p>Sends a collection of string objects to the serial port/device identified by the given file descriptor.</p>
161     *
162     * @param charset
163     *           The character set to use for encoding/decoding bytes to/from text characters
164     * @param data
165     *           A collection of string objects (or an array) of data to be transmitted. (variable-length-argument)
166     */
167    public void write(Charset charset, Collection<? extends CharSequence> data) throws IllegalStateException, IOException;
168
169    /**
170     * <p>Sends a collection of ASCII string objects to the serial port/device identified by the given file descriptor.</p>
171     *
172     * @param data
173     *           A collection of string objects (or an array) of data to be transmitted. (variable-length-argument)
174     */
175    public void write(Collection<? extends CharSequence> data) throws IllegalStateException, IOException;
176
177    /**
178     * <p>Sends one or more string objects each appended with a line terminator (CR+LF) to the serial port/device.</p>
179     *
180     * @param charset
181     *           The character set to use for encoding/decoding bytes to/from text characters
182     * @param data
183     *           One or more string objects (or an array) of data to be transmitted. (variable-length-argument)
184     */
185    public void writeln(Charset charset, CharSequence ... data) throws IllegalStateException, IOException;
186
187    /**
188     * <p>Sends one or more ASCII string objects each appended with a line terminator (CR+LF) to the serial port/device.</p>
189     *
190     * @param data
191     *           One or more ASCII string objects (or an array) of data to be transmitted. (variable-length-argument)
192     */
193    public void writeln(CharSequence ... data) throws IllegalStateException, IOException;
194
195    /**
196     * <p>Sends a collection of string objects each appended with a line terminator (CR+LF) to the serial port/device.</p>
197     *
198     * @param charset
199     *           The character set to use for encoding/decoding bytes to/from text characters
200     * @param data
201     *           A collection of string objects (or an array) of data to be transmitted. (variable-length-argument)
202     */
203    public void writeln(Charset charset, Collection<? extends CharSequence> data) throws IllegalStateException, IOException;
204
205    /**
206     * <p>Sends a collection of ASCII string objects each appended with a line terminator (CR+LF) to the serial port/device.</p>
207     *
208     * @param data
209     *           A collection of ASCII string objects (or an array) of data to be transmitted. (variable-length-argument)
210     */
211    public void writeln(Collection<? extends CharSequence> data) throws IllegalStateException, IOException;
212
213
214
215}