001    /* 
002       Copyright (C) 2005-2007 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.sound.sampled;
039    
040    /**
041     * The DataLine interface adds data-related functionality to the Line
042     * interface.  For example, it adds methods to start and stop the data
043     * on the line.
044     * @since 1.3 
045     */
046    public interface DataLine extends Line
047    {
048      /**
049       * This class extends Line.Info with information specific to DataLine.
050       * In particular it adds information about buffer sizes, and about supported
051       * audio formats.
052       * @since 1.3
053       */
054      class Info extends Line.Info
055      {
056        private int minBufferSize;
057        private int maxBufferSize;
058        private AudioFormat[] formats;
059    
060        /**
061         * Create a new Info given the line's class and a supported
062         * audio format.  The buffer sizes default to AudioSystem.NOT_SPECIFIED.
063         * @param klass the class of the line
064         * @param fmt the supported format
065         */
066        public Info(Class<?> klass, AudioFormat fmt)
067        {
068          super(klass);
069          this.minBufferSize = AudioSystem.NOT_SPECIFIED;
070          this.maxBufferSize = AudioSystem.NOT_SPECIFIED;
071          this.formats = new AudioFormat[] { fmt };
072        }
073    
074        /**
075         * Create a new Info given the line's class, the supported audio formats,
076         * the minimum buffer size, and the maximum buffer size.
077         * @param klass the class of the linee
078         * @param fmts the supported audio formats
079         * @param minSize the minimum buffer size
080         * @param maxSize the maximum buffer size
081         */
082        public Info(Class<?> klass, AudioFormat[] fmts, int minSize, int maxSize)
083        {
084          super(klass);
085          this.minBufferSize = minSize;
086          this.maxBufferSize = maxSize;
087          this.formats = fmts;
088        }
089    
090        /**
091         * Create a new Info given the line's class, a supported
092         * audio format, and a buffer size.  Both the minimum and maximum
093         * sizes are set from this size.
094         * @param klass the class of the line
095         * @param fmt the supported format
096         * @param size the buffer size
097         */
098        public Info(Class<?> klass, AudioFormat fmt, int size)
099        {
100          super(klass);
101          this.minBufferSize = size;
102          this.maxBufferSize = size;
103          this.formats = new AudioFormat[] { fmt };
104        }
105    
106        /**
107         * Return the supported audio formats.
108         */
109        public AudioFormat[] getFormats()
110        {
111          // FIXME: clone?
112          return formats;
113        }
114    
115        /**
116         * Return the maximum buffer size.
117         */
118        public int getMaxBufferSize()
119        {
120          return maxBufferSize;
121        }
122    
123        /**
124         * Return the minimum buffer size.
125         */
126        public int getMinBufferSize()
127        {
128          return minBufferSize;
129        }
130    
131        /**
132         * Return true if the indicated audio format is supported by this
133         * Info, false otherwise.
134         * @param fmt the audio format
135         * @return true if the format is supported
136         */
137        public boolean isFormatSupported(AudioFormat fmt)
138        {
139          for (int i = 0; i < formats.length; ++i)
140            {
141              if (fmt.matches(formats[i]))
142                return true;
143            }
144          return false;
145        }
146    
147        /**
148         * Return true if this Info matches another Info object.
149         */
150        public boolean matches(Line.Info o)
151        {
152          if (! super.matches(o) || ! (o instanceof Info))
153            return false;
154    
155          Info other = (Info) o;
156          if (minBufferSize < other.minBufferSize ||
157              maxBufferSize > other.maxBufferSize)
158            return false;
159          
160          for (int i = 0; i < formats.length; ++i)
161            {
162              boolean ok = false;
163              for (int j = 0; j < other.formats.length; ++j)
164                {
165                  if (formats[i].matches(other.formats[j]))
166                    {
167                      ok = true;
168                      break;
169                    }
170                }
171              if (! ok)
172                return false;
173            }
174          
175          return true;
176        }
177    
178        /**
179         * Return a description of this Info object.
180         */
181        public String toString()
182        {
183          StringBuffer result = new StringBuffer();
184          result.append("formats: [");
185          for (int i = 0; i < formats.length; ++i)
186            {
187              if (i > 0)
188                result.append(", ");
189              result.append(formats[i].toString());
190            }
191          
192          result.append("]; minBufferSize: ");
193          result.append(minBufferSize);
194          result.append("; maxBufferSize: ");
195          result.append(maxBufferSize);
196          return result.toString();
197        }
198        
199      } // end class: Info
200    
201      /**
202       * Return the number of bytes currently available on this DataLine.
203       */
204      int available();
205    
206      /**
207       * This method blocks until whatever data is buffered in the
208       * DataLine's internal buffer has been drained.
209       */
210      void drain();
211    
212      /**
213       * This flushes the DataLine by discarding any buffered data.
214       */
215      void flush();
216    
217      /**
218       * Returns the size of the DataLine's internal buffer, in bytes.
219       */
220      int getBufferSize();
221    
222      /**
223       * Return the current format of the data associated with this DataLine.
224       */
225      AudioFormat getFormat();
226    
227      /**
228       * Return the current frame position.
229       */
230      int getFramePosition();
231    
232      /**
233       * Return the volume level for this DataLine.
234       */
235      float getLevel();
236    
237      /**
238       * Return the current frame position. 
239       * @since 1.5
240       */
241      long getLongFramePosition();
242    
243      /**
244       * Return the number of microseconds this DataLine has been playing.
245       */
246      long getMicrosecondPosition();
247    
248      /**
249       * Return true if this line is active, meaning that it is actively
250       * performing audio I/O.
251       */
252      boolean isActive();
253    
254      /**
255       * Return true if this line is running, meaning that it has been
256       * started.  When the line is stopped, this method will return false.
257       */
258      boolean isRunning();
259    
260      /**
261       * Start processing data.  This will emit a START event.
262       */
263      void start();
264    
265      /**
266       * Stop processing data.  This will emit a STOP event.
267       */
268      void stop();
269    }