1. /*

  2.  * @(#)SourceDataLine.java	1.20 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.sound.sampled;	

  9. 

  10. 

  11. /**

  12.  * A source data line is a data line to which data may be written.  It acts as

  13.  * a source to its mixer. An application writes audio bytes to a source data line,

  14.  * which handles the buffering of the bytes and delivers them to the mixer.

  15.  * The mixer may mix the samples with those from other sources and then deliver

  16.  * the mix to a target such as an output port (which may represent an audio output    

  17.  * device on a sound card).

  18.  * <p>

  19.  * Note that the naming convention for this interface reflects the relationship

  20.  * between the line and its mixer.  From the perspective of an application,

  21.  * a source data line may act as a target for audio data.

  22.  * <p>

  23.  * A source data line can be obtained from a mixer by invoking the 

  24.  * <code>{@link Mixer#getLine getLine}</code> method of <code>Mixer</code> with 

  25.  * an appropriate <code>{@link DataLine.Info}</code> object.

  26.  * <p>

  27.  * The <code>SourceDataLine</code> interface provides a method for writing 

  28.  * audio data to the data line's buffer. Applications that play or mix 

  29.  * audio should write data to the source data line quickly enough to keep the 

  30.  * buffer from underflowing (emptying), which could cause discontinuities in 

  31.  * the audio that are perceived as clicks.  Applications can use the 

  32.  * <code>{@link DataLine#available available}</code> method defined in the

  33.  * <code>DataLine</code> interface to determine the amount of data currently

  34.  * queued in the data line's buffer.  The amount of data which can be written

  35.  * to the buffer without blocking is the difference between the buffer size

  36.  * and the amount of queued data.  If the delivery of audio output 

  37.  * stops due to underflow, a <code>{@link LineEvent.Type#STOP STOP}</code> event is 

  38.  * generated.  A <code>{@link LineEvent.Type#START START}</code> event is generated

  39.  * when the audio output resumes. 

  40.  *

  41.  * @author Kara Kytle

  42.  * @version 1.20 03/12/19

  43.  * @see Mixer

  44.  * @see DataLine

  45.  * @see TargetDataLine

  46.  * @since 1.3

  47.  */

  48. public interface SourceDataLine extends DataLine {

  49. 	

  50. 

  51.     /**

  52.      * Opens the line with the specified format and suggested buffer size,

  53.      * causing the line to acquire any required

  54.      * system resources and become operational.

  55.      * <p>

  56.      * The buffer size is specified in bytes, but must represent an integral 

  57.      * number of sample frames.  Invoking this method with a requested buffer 

  58.      * size that does not meet this requirement may result in an 

  59.      * IllegalArgumentException.  The actual buffer size for the open line may 

  60.      * differ from the requested buffer size.  The value actually set may be 

  61.      * queried by subsequently calling <code>{@link DataLine#getBufferSize}</code>.  

  62.      * <p>

  63.      * If this operation succeeds, the line is marked as open, and an 

  64.      * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched to the 

  65.      * line's listeners.

  66.      * <p>

  67.      * Invoking this method on a line which is already open is illegal

  68.      * and may result in an <code>IllegalStateException</code>.

  69.      * <p>

  70.      * Note that some lines, once closed, cannot be reopened.  Attempts

  71.      * to reopen such a line will always result in a 

  72.      * <code>LineUnavailableException</code>.

  73.      *

  74.      * @param format the desired audio format

  75.      * @param bufferSize the desired buffer size

  76.      * @throws LineUnavailableException if the line cannot be

  77.      * opened due to resource restrictions

  78.      * @throws IllegalArgumentException if the buffer size does not represent

  79.      * an integral number of sample frames,

  80.      * or if <code>format</code> is not fully specified or invalid

  81.      * @throws IllegalStateException if the line is already open

  82.      * @throws SecurityException if the line cannot be

  83.      * opened due to security restrictions

  84.      *

  85.      * @see #open(AudioFormat)

  86.      * @see Line#open

  87.      * @see Line#close

  88.      * @see Line#isOpen

  89.      * @see LineEvent

  90.      */

  91.     public void open(AudioFormat format, int bufferSize) throws LineUnavailableException;

  92. 

  93. 

  94.     /**

  95.      * Opens the line with the specified format, causing the line to acquire any 

  96.      * required system resources and become operational.  

  97.      *   

  98.      * <p>

  99.      * The implementation chooses a buffer size, which is measured in bytes but 

  100.      * which encompasses an integral number of sample frames.  The buffer size 

  101.      * that the system has chosen may be queried by subsequently calling 

  102.      * <code>{@link DataLine#getBufferSize}</code>.

  103.      * <p>

  104.      * If this operation succeeds, the line is marked as open, and an 

  105.      * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched to the 

  106.      * line's listeners.

  107.      * <p>

  108.      * Invoking this method on a line which is already open is illegal

  109.      * and may result in an <code>IllegalStateException</code>.

  110.      * <p>

  111.      * Note that some lines, once closed, cannot be reopened.  Attempts

  112.      * to reopen such a line will always result in a 

  113.      * <code>LineUnavailableException</code>.

  114.      *

  115.      * @param format the desired audio format

  116.      * @throws LineUnavailableException if the line cannot be

  117.      * opened due to resource restrictions

  118.      * @throws IllegalArgumentException if <code>format</code>

  119.      * is not fully specified or invalid

  120.      * @throws IllegalStateException if the line is already open

  121.      * @throws SecurityException if the line cannot be

  122.      * opened due to security restrictions

  123.      *

  124.      * @see #open(AudioFormat, int)

  125.      * @see Line#open

  126.      * @see Line#close

  127.      * @see Line#isOpen

  128.      * @see LineEvent

  129.      */

  130.     public void open(AudioFormat format) throws LineUnavailableException;

  131. 

  132. 

  133.     /**

  134.      * Writes audio data to the mixer via this source data line.  The requested 

  135.      * number of bytes of data are read from the specified array, 

  136.      * starting at the given offset into the array, and written to the data 

  137.      * line's buffer.  If the caller attempts to write more data than can 

  138.      * currently be written (see <code>{@link DataLine#available available}</code>), 

  139.      * this method blocks until the requested amount of data has been written.  

  140.      * This applies even if the requested amount of data to write is greater 

  141.      * than the data line's buffer size.  However, if the data line is closed, 

  142.      * stopped, or flushed before the requested amount has been written,

  143.      * the method no longer blocks, but returns the number of bytes 

  144.      * written thus far. 

  145.      * <p>

  146.      * The number of bytes that can be written without blocking can be ascertained

  147.      * using the <code>{@link DataLine#available available}</code> method of the

  148.      * <code>DataLine</code> interface.  (While it is guaranteed that

  149.      * this number of bytes can be written without blocking, there is no guarantee

  150.      * that attempts to write additional data will block.)

  151.      * <p>

  152.      * The number of bytes to write must represent an integral number of

  153.      * sample frames, such that:

  154.      * <br>

  155.      * <center><code>[ bytes written ] % [frame size in bytes ] == 0</code></center>

  156.      * <br>

  157.      * The return value will always meet this requirement.  A request to write a 

  158.      * number of bytes representing a non-integral number of sample frames cannot 

  159.      * be fulfilled and may result in an <code>IllegalArgumentException</code>.

  160.      *

  161.      * @param b a byte array containing data to be written to the data line

  162.      * @param len the length, in bytes, of the valid data in the array 

  163.      * (in other words, the requested amount of data to write, in bytes)

  164.      * @param off the offset from the beginning of the array, in bytes

  165.      * @return the number of bytes actually written

  166.      * @throws IllegalArgumentException if the requested number of bytes does

  167.      * not represent an integral number of sample frames,

  168.      * or if <code>len</code> is negative

  169.      * @throws ArrayIndexOutOfBoundsException if <code>off</code> is negative,

  170.      * or <code>off+len</code> is greater than the length of the array

  171.      * <code>b</code>.

  172.      *

  173.      * @see TargetDataLine#read

  174.      * @see DataLine#available

  175.      */	

  176.     public int write(byte[] b, int off, int len);

  177. 

  178.     /**

  179.      * Obtains the number of sample frames of audio data that can be written to 

  180.      * the mixer, via this data line, without blocking.  Note that the return 

  181.      * value measures sample frames, not bytes. 

  182.      * @return the number of sample frames currently available for writing

  183.      * @see TargetDataLine#availableRead

  184.      */

  185.     //public int availableWrite();

  186. }