001/*
002   Copyright (C) 2005-2007 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.sound.sampled;
039
040import gnu.java.lang.CPStringBuilder;
041
042/**
043 * The DataLine interface adds data-related functionality to the Line
044 * interface.  For example, it adds methods to start and stop the data
045 * on the line.
046 * @since 1.3
047 */
048public interface DataLine extends Line
049{
050  /**
051   * This class extends Line.Info with information specific to DataLine.
052   * In particular it adds information about buffer sizes, and about supported
053   * audio formats.
054   * @since 1.3
055   */
056  class Info extends Line.Info
057  {
058    private int minBufferSize;
059    private int maxBufferSize;
060    private AudioFormat[] formats;
061
062    /**
063     * Create a new Info given the line's class and a supported
064     * audio format.  The buffer sizes default to AudioSystem.NOT_SPECIFIED.
065     * @param klass the class of the line
066     * @param fmt the supported format
067     */
068    public Info(Class<?> klass, AudioFormat fmt)
069    {
070      super(klass);
071      this.minBufferSize = AudioSystem.NOT_SPECIFIED;
072      this.maxBufferSize = AudioSystem.NOT_SPECIFIED;
073      this.formats = new AudioFormat[] { fmt };
074    }
075
076    /**
077     * Create a new Info given the line's class, the supported audio formats,
078     * the minimum buffer size, and the maximum buffer size.
079     * @param klass the class of the linee
080     * @param fmts the supported audio formats
081     * @param minSize the minimum buffer size
082     * @param maxSize the maximum buffer size
083     */
084    public Info(Class<?> klass, AudioFormat[] fmts, int minSize, int maxSize)
085    {
086      super(klass);
087      this.minBufferSize = minSize;
088      this.maxBufferSize = maxSize;
089      this.formats = fmts;
090    }
091
092    /**
093     * Create a new Info given the line's class, a supported
094     * audio format, and a buffer size.  Both the minimum and maximum
095     * sizes are set from this size.
096     * @param klass the class of the line
097     * @param fmt the supported format
098     * @param size the buffer size
099     */
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     */
111    public AudioFormat[] getFormats()
112    {
113      // FIXME: clone?
114      return formats;
115    }
116
117    /**
118     * Return the maximum buffer size.
119     */
120    public int getMaxBufferSize()
121    {
122      return maxBufferSize;
123    }
124
125    /**
126     * Return the minimum buffer size.
127     */
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     */
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     */
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     */
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   */
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   */
212  void drain();
213
214  /**
215   * This flushes the DataLine by discarding any buffered data.
216   */
217  void flush();
218
219  /**
220   * Returns the size of the DataLine's internal buffer, in bytes.
221   */
222  int getBufferSize();
223
224  /**
225   * Return the current format of the data associated with this DataLine.
226   */
227  AudioFormat getFormat();
228
229  /**
230   * Return the current frame position.
231   */
232  int getFramePosition();
233
234  /**
235   * Return the volume level for this DataLine.
236   */
237  float getLevel();
238
239  /**
240   * Return the current frame position.
241   * @since 1.5
242   */
243  long getLongFramePosition();
244
245  /**
246   * Return the number of microseconds this DataLine has been playing.
247   */
248  long getMicrosecondPosition();
249
250  /**
251   * Return true if this line is active, meaning that it is actively
252   * performing audio I/O.
253   */
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   */
260  boolean isRunning();
261
262  /**
263   * Start processing data.  This will emit a START event.
264   */
265  void start();
266
267  /**
268   * Stop processing data.  This will emit a STOP event.
269   */
270  void stop();
271}