001/**
002 * Copyright 2017-2019, Digi International Inc.
003 *
004 * This Source Code Form is subject to the terms of the Mozilla Public
005 * License, v. 2.0. If a copy of the MPL was not distributed with this
006 * file, you can obtain one at http://mozilla.org/MPL/2.0/.
007 *
008 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
009 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
010 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
011 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
012 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
013 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
014 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
015 */
016package com.digi.xbee.api.connection;
017
018import java.io.IOException;
019import java.io.InputStream;
020import java.io.OutputStream;
021
022import com.digi.xbee.api.exceptions.InterfaceInUseException;
023import com.digi.xbee.api.exceptions.InvalidConfigurationException;
024import com.digi.xbee.api.exceptions.InvalidInterfaceException;
025import com.digi.xbee.api.exceptions.PermissionDeniedException;
026
027/**
028 * This interface represents a protocol independent connection with an XBee 
029 * device.
030 * 
031 * <p>The connection can be made using sockets, serial port, etc.</p>
032 * 
033 * <p>As an important point, the class implementing this interface must call 
034 * {@code this.notify()} whenever new data is available to read. Not doing this 
035 * will make the {@code DataReader} class to wait forever for new data.</p>
036 */
037public interface IConnectionInterface {
038
039        /**
040         * Attempts to open the connection interface.
041         * 
042         * @throws InterfaceInUseException if the interface is in use by other 
043         *                                 application(s).
044         * @throws InvalidConfigurationException if the configuration used to open 
045         *                                       the interface is invalid.
046         * @throws InvalidInterfaceException if the interface is invalid or does 
047         *                                   not exist.
048         * @throws PermissionDeniedException if you do not have permissions to 
049         *                                   access the interface.
050         * 
051         * @see #close()
052         * @see #isOpen()
053         */
054        public void open() throws InterfaceInUseException, InvalidInterfaceException, InvalidConfigurationException, PermissionDeniedException;
055        
056        /**
057         * Attempts to close the connection interface.
058         * 
059         * @see #isOpen()
060         * @see #open()
061         */
062        public void close();
063        
064        /**
065         * Returns whether the connection interface is open or not.
066         * 
067         * @return {@code true} if the connection interface is open, {@code false} 
068         *         otherwise.
069         *         
070         * @see #close()
071         * @see #open()
072         */
073        public boolean isOpen();
074        
075        /**
076         * Returns the connection interface input stream to read data from.
077         * 
078         * @return The connection interface input stream to read data from.
079         * 
080         * @see #getOutputStream()
081         * @see java.io.InputStream
082         */
083        public InputStream getInputStream();
084        
085        /**
086         * Returns the connection interface output stream to write data to.
087         * 
088         * @return The connection interface output stream to write data to.
089         * 
090         * @see #getInputStream()
091         * @see java.io.OutputStream
092         */
093        public OutputStream getOutputStream();
094        
095        /**
096         * Writes the given data in the connection interface.
097         * 
098         * @param data The data to be written in the connection interface.
099         * 
100         * @throws IOException if there is any problem writing to the output stream.
101         * @throws NullPointerException if {@code data == null}.
102         * 
103         * @see #writeData(byte[], int, int)
104         */
105        public void writeData(byte[] data) throws IOException;
106        
107        /**
108         * Writes the given data in the connection interface.
109         * 
110         * @param data The data to be written in the connection interface.
111         * @param offset The start offset in the data to write.
112         * @param length The number of bytes to write.
113         * 
114         * @throws IllegalArgumentException if {@code offset < 0} or
115         *                                  if {@code length < 1} or
116         *                                  if {@code offset >= data.length} or
117         *                                  if {@code offset + length > data.length}.
118         * @throws IOException if there is any problem writing to the output stream.
119         * @throws NullPointerException if {@code data == null}.
120         * 
121         * @see #writeData(byte[])
122         */
123        public void writeData(byte[] data, int offset, int length) throws IOException;
124        
125        /**
126         * Reads data from the connection interface and stores it in the provided 
127         * byte array returning the number of read bytes.
128         * 
129         * @param data The byte array to store the read data.
130         * 
131         * @return The number of bytes read.
132         * 
133         * @throws IOException if there is any problem reading from the input stream.
134         * @throws NullPointerException if {@code data == null}.
135         * 
136         * @see #readData(byte[], int, int)
137         */
138        public int readData(byte[] data) throws IOException;
139        
140        /**
141         * Reads the given number of bytes at the given offset from the connection
142         * interface and stores it in the provided byte array returning the number
143         * of read bytes.
144         * 
145         * @param data The byte array to store the read data.
146         * @param offset The start offset in data array at which the data is written.
147         * @param length Maximum number of bytes to read.
148         * 
149         * @return The number of bytes read.
150         * 
151         * @throws IllegalArgumentException if {@code offset < 0} or
152         *                                  if {@code length < 1} or
153         *                                  if {@code offset >= data.length} or
154         *                                  if {@code offset + length > data.length}.
155         * @throws IOException if there is any problem reading from the input stream.
156         * @throws NullPointerException if {@code data == null}.
157         * 
158         * @see #readData(byte[])
159         */
160        public int readData(byte[] data, int offset, int length) throws IOException;
161        
162        /**
163         * Returns the connection type of the interface.
164         * 
165         * @return The connection type of the interface.
166         * 
167         * @see ConnectionType
168         * 
169         * @since 1.3.0
170         */
171        public ConnectionType getConnectionType();
172}