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    import 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     */
048    public 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    }