1 /* 2 Copyright (C) 2005-2007 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 package javax.sound.sampled; 39 40 import gnu.java.lang.CPStringBuilder; 41 42 /** 43 * The DataLine interface adds data-related functionality to the Line 44 * interface. For example, it adds methods to start and stop the data 45 * on the line. 46 * @since 1.3 47 */ 48 public interface DataLine extends Line 49 { 50 /** 51 * This class extends Line.Info with information specific to DataLine. 52 * In particular it adds information about buffer sizes, and about supported 53 * audio formats. 54 * @since 1.3 55 */ 56 class Info extends Line.Info 57 { 58 private int minBufferSize; 59 private int maxBufferSize; 60 private AudioFormat[] formats; 61 62 /** 63 * Create a new Info given the line's class and a supported 64 * audio format. The buffer sizes default to AudioSystem.NOT_SPECIFIED. 65 * @param klass the class of the line 66 * @param fmt the supported format 67 */ Info(Class<?> klass, AudioFormat fmt)68 public Info(Class<?> klass, AudioFormat fmt) 69 { 70 super(klass); 71 this.minBufferSize = AudioSystem.NOT_SPECIFIED; 72 this.maxBufferSize = AudioSystem.NOT_SPECIFIED; 73 this.formats = new AudioFormat[] { fmt }; 74 } 75 76 /** 77 * Create a new Info given the line's class, the supported audio formats, 78 * the minimum buffer size, and the maximum buffer size. 79 * @param klass the class of the linee 80 * @param fmts the supported audio formats 81 * @param minSize the minimum buffer size 82 * @param maxSize the maximum buffer size 83 */ Info(Class<?> klass, AudioFormat[] fmts, int minSize, int maxSize)84 public Info(Class<?> klass, AudioFormat[] fmts, int minSize, int maxSize) 85 { 86 super(klass); 87 this.minBufferSize = minSize; 88 this.maxBufferSize = maxSize; 89 this.formats = fmts; 90 } 91 92 /** 93 * Create a new Info given the line's class, a supported 94 * audio format, and a buffer size. Both the minimum and maximum 95 * sizes are set from this size. 96 * @param klass the class of the line 97 * @param fmt the supported format 98 * @param size the buffer size 99 */ Info(Class<?> klass, AudioFormat fmt, int size)100 public Info(Class<?> klass, AudioFormat fmt, int size) 101 { 102 super(klass); 103 this.minBufferSize = size; 104 this.maxBufferSize = size; 105 this.formats = new AudioFormat[] { fmt }; 106 } 107 108 /** 109 * Return the supported audio formats. 110 */ getFormats()111 public AudioFormat[] getFormats() 112 { 113 // FIXME: clone? 114 return formats; 115 } 116 117 /** 118 * Return the maximum buffer size. 119 */ getMaxBufferSize()120 public int getMaxBufferSize() 121 { 122 return maxBufferSize; 123 } 124 125 /** 126 * Return the minimum buffer size. 127 */ getMinBufferSize()128 public int getMinBufferSize() 129 { 130 return minBufferSize; 131 } 132 133 /** 134 * Return true if the indicated audio format is supported by this 135 * Info, false otherwise. 136 * @param fmt the audio format 137 * @return true if the format is supported 138 */ isFormatSupported(AudioFormat fmt)139 public boolean isFormatSupported(AudioFormat fmt) 140 { 141 for (int i = 0; i < formats.length; ++i) 142 { 143 if (fmt.matches(formats[i])) 144 return true; 145 } 146 return false; 147 } 148 149 /** 150 * Return true if this Info matches another Info object. 151 */ matches(Line.Info o)152 public boolean matches(Line.Info o) 153 { 154 if (! super.matches(o) || ! (o instanceof Info)) 155 return false; 156 157 Info other = (Info) o; 158 if (minBufferSize < other.minBufferSize || 159 maxBufferSize > other.maxBufferSize) 160 return false; 161 162 for (int i = 0; i < formats.length; ++i) 163 { 164 boolean ok = false; 165 for (int j = 0; j < other.formats.length; ++j) 166 { 167 if (formats[i].matches(other.formats[j])) 168 { 169 ok = true; 170 break; 171 } 172 } 173 if (! ok) 174 return false; 175 } 176 177 return true; 178 } 179 180 /** 181 * Return a description of this Info object. 182 */ toString()183 public String toString() 184 { 185 CPStringBuilder result = new CPStringBuilder(); 186 result.append("formats: ["); 187 for (int i = 0; i < formats.length; ++i) 188 { 189 if (i > 0) 190 result.append(", "); 191 result.append(formats[i].toString()); 192 } 193 194 result.append("]; minBufferSize: "); 195 result.append(minBufferSize); 196 result.append("; maxBufferSize: "); 197 result.append(maxBufferSize); 198 return result.toString(); 199 } 200 201 } // end class: Info 202 203 /** 204 * Return the number of bytes currently available on this DataLine. 205 */ available()206 int available(); 207 208 /** 209 * This method blocks until whatever data is buffered in the 210 * DataLine's internal buffer has been drained. 211 */ drain()212 void drain(); 213 214 /** 215 * This flushes the DataLine by discarding any buffered data. 216 */ flush()217 void flush(); 218 219 /** 220 * Returns the size of the DataLine's internal buffer, in bytes. 221 */ getBufferSize()222 int getBufferSize(); 223 224 /** 225 * Return the current format of the data associated with this DataLine. 226 */ getFormat()227 AudioFormat getFormat(); 228 229 /** 230 * Return the current frame position. 231 */ getFramePosition()232 int getFramePosition(); 233 234 /** 235 * Return the volume level for this DataLine. 236 */ getLevel()237 float getLevel(); 238 239 /** 240 * Return the current frame position. 241 * @since 1.5 242 */ getLongFramePosition()243 long getLongFramePosition(); 244 245 /** 246 * Return the number of microseconds this DataLine has been playing. 247 */ getMicrosecondPosition()248 long getMicrosecondPosition(); 249 250 /** 251 * Return true if this line is active, meaning that it is actively 252 * performing audio I/O. 253 */ isActive()254 boolean isActive(); 255 256 /** 257 * Return true if this line is running, meaning that it has been 258 * started. When the line is stopped, this method will return false. 259 */ isRunning()260 boolean isRunning(); 261 262 /** 263 * Start processing data. This will emit a START event. 264 */ start()265 void start(); 266 267 /** 268 * Stop processing data. This will emit a STOP event. 269 */ stop()270 void stop(); 271 } 272