001/**
002 * Copyright (c) 2014 Digi International Inc.,
003 * All rights not expressly granted are reserved.
004 *
005 * This Source Code Form is subject to the terms of the Mozilla Public
006 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
007 * You can obtain one at http://mozilla.org/MPL/2.0/.
008 *
009 * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
010 * =======================================================================
011 */
012package com.digi.xbee.api.connection;
013
014import java.io.IOException;
015import java.io.InputStream;
016import java.io.OutputStream;
017
018import com.digi.xbee.api.exceptions.InterfaceInUseException;
019import com.digi.xbee.api.exceptions.InvalidConfigurationException;
020import com.digi.xbee.api.exceptions.InvalidInterfaceException;
021import com.digi.xbee.api.exceptions.PermissionDeniedException;
022
023/**
024 * This interface represents a protocol independent connection with an XBee 
025 * device.
026 * 
027 * <p>The connection can be made using sockets, serial port, etc.</p>
028 * 
029 * <p>As an important point, the class implementing this interface must call 
030 * {@code this.notify()} whenever new data is available to read. Not doing this 
031 * will make the {@code DataReader} class to wait forever for new data.</p>
032 */
033public interface IConnectionInterface {
034
035        /**
036         * Attempts to open the connection interface.
037         * 
038         * @throws InterfaceInUseException if the interface is in use by other 
039         *                                 application(s).
040         * @throws InvalidConfigurationException if the configuration used to open 
041         *                                       the interface is invalid.
042         * @throws InvalidInterfaceException if the interface is invalid or does 
043         *                                   not exist.
044         * @throws PermissionDeniedException if you do not have permissions to 
045         *                                   access the interface.
046         * 
047         * @see #close()
048         * @see #isOpen()
049         */
050        public void open() throws InterfaceInUseException, InvalidInterfaceException, InvalidConfigurationException, PermissionDeniedException;
051        
052        /**
053         * Attempts to close the connection interface.
054         * 
055         * @see #isOpen()
056         * @see #open()
057         */
058        public void close();
059        
060        /**
061         * Returns whether the connection interface is open or not.
062         * 
063         * @return {@code true} if the connection interface is open, {@code false} 
064         *         otherwise.
065         *         
066         * @see #close()
067         * @see #open()
068         */
069        public boolean isOpen();
070        
071        /**
072         * Returns the connection interface input stream to read data from.
073         * 
074         * @return The connection interface input stream to read data from.
075         * 
076         * @see #getOutputStream()
077         * @see java.io.InputStream
078         */
079        public InputStream getInputStream();
080        
081        /**
082         * Returns the connection interface output stream to write data to.
083         * 
084         * @return The connection interface output stream to write data to.
085         * 
086         * @see #getInputStream()
087         * @see java.io.OutputStream
088         */
089        public OutputStream getOutputStream();
090        
091        /**
092         * Writes the given data in the connection interface.
093         * 
094         * @param data The data to be written in the connection interface.
095         * 
096         * @throws IOException if there is any problem writing to the output stream.
097         * @throws NullPointerException if {@code data == null}.
098         * 
099         * @see #writeData(byte[], int, int)
100         */
101        public void writeData(byte[] data) throws IOException;
102        
103        /**
104         * Writes the given data in the connection interface.
105         * 
106         * @param data The data to be written in the connection interface.
107         * @param offset The start offset in the data to write.
108         * @param length The number of bytes to write.
109         * 
110         * @throws IllegalArgumentException if {@code offset < 0} or
111         *                                  if {@code length < 1} or
112         *                                  if {@code offset >= data.length} or
113         *                                  if {@code offset + length > data.length}.
114         * @throws IOException if there is any problem writing to the output stream.
115         * @throws NullPointerException if {@code data == null}.
116         * 
117         * @see #writeData(byte[])
118         */
119        public void writeData(byte[] data, int offset, int length) throws IOException;
120        
121        /**
122         * Reads data from the connection interface and stores it in the provided 
123         * byte array returning the number of read bytes.
124         * 
125         * @param data The byte array to store the read data.
126         * 
127         * @return The number of bytes read.
128         * 
129         * @throws IOException if there is any problem reading from the input stream.
130         * @throws NullPointerException if {@code data == null}.
131         * 
132         * @see #readData(byte[], int, int)
133         */
134        public int readData(byte[] data) throws IOException;
135        
136        /**
137         * Reads the given number of bytes at the given offset from the connection
138         * interface and stores it in the provided byte array returning the number
139         * of read bytes.
140         * 
141         * @param data The byte array to store the read data.
142         * @param offset The start offset in data array at which the data is written.
143         * @param length Maximum number of bytes to read.
144         * 
145         * @return The number of bytes read.
146         * 
147         * @throws IllegalArgumentException if {@code offset < 0} or
148         *                                  if {@code length < 1} or
149         *                                  if {@code offset >= data.length} or
150         *                                  if {@code offset + length > data.length}.
151         * @throws IOException if there is any problem reading from the input stream.
152         * @throws NullPointerException if {@code data == null}.
153         * 
154         * @see #readData(byte[])
155         */
156        public int readData(byte[] data, int offset, int length) throws IOException;
157}