2362N/A * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A source data line is a data line to which data may be written. It acts as 0N/A * a source to its mixer. An application writes audio bytes to a source data line, 0N/A * which handles the buffering of the bytes and delivers them to the mixer. 0N/A * The mixer may mix the samples with those from other sources and then deliver 0N/A * the mix to a target such as an output port (which may represent an audio output 0N/A * device on a sound card). 0N/A * Note that the naming convention for this interface reflects the relationship 0N/A * between the line and its mixer. From the perspective of an application, 0N/A * a source data line may act as a target for audio data. 0N/A * A source data line can be obtained from a mixer by invoking the 0N/A * <code>{@link Mixer#getLine getLine}</code> method of <code>Mixer</code> with 0N/A * an appropriate <code>{@link DataLine.Info}</code> object. 0N/A * The <code>SourceDataLine</code> interface provides a method for writing 0N/A * audio data to the data line's buffer. Applications that play or mix 0N/A * audio should write data to the source data line quickly enough to keep the 0N/A * buffer from underflowing (emptying), which could cause discontinuities in 0N/A * the audio that are perceived as clicks. Applications can use the 0N/A * <code>{@link DataLine#available available}</code> method defined in the 0N/A * <code>DataLine</code> interface to determine the amount of data currently 0N/A * queued in the data line's buffer. The amount of data which can be written 0N/A * to the buffer without blocking is the difference between the buffer size 0N/A * and the amount of queued data. If the delivery of audio output 0N/A * stops due to underflow, a <code>{@link LineEvent.Type#STOP STOP}</code> event is 0N/A * generated. A <code>{@link LineEvent.Type#START START}</code> event is generated 0N/A * when the audio output resumes. 0N/A * @author Kara Kytle 0N/A * @see TargetDataLine 0N/A * Opens the line with the specified format and suggested buffer size, 0N/A * causing the line to acquire any required 0N/A * system resources and become operational. 0N/A * The buffer size is specified in bytes, but must represent an integral 0N/A * number of sample frames. Invoking this method with a requested buffer 0N/A * size that does not meet this requirement may result in an 0N/A * IllegalArgumentException. The actual buffer size for the open line may 0N/A * differ from the requested buffer size. The value actually set may be 0N/A * queried by subsequently calling <code>{@link DataLine#getBufferSize}</code>. 0N/A * If this operation succeeds, the line is marked as open, and an 0N/A * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched to the 0N/A * Invoking this method on a line which is already open is illegal 0N/A * and may result in an <code>IllegalStateException</code>. 0N/A * Note that some lines, once closed, cannot be reopened. Attempts 0N/A * to reopen such a line will always result in a 0N/A * <code>LineUnavailableException</code>. 0N/A * @param format the desired audio format 0N/A * @param bufferSize the desired buffer size 0N/A * @throws LineUnavailableException if the line cannot be 0N/A * opened due to resource restrictions 0N/A * @throws IllegalArgumentException if the buffer size does not represent 0N/A * an integral number of sample frames, 0N/A * or if <code>format</code> is not fully specified or invalid 0N/A * @throws IllegalStateException if the line is already open 0N/A * @throws SecurityException if the line cannot be 0N/A * opened due to security restrictions 0N/A * @see #open(AudioFormat) 0N/A * Opens the line with the specified format, causing the line to acquire any 0N/A * required system resources and become operational. 0N/A * The implementation chooses a buffer size, which is measured in bytes but 0N/A * which encompasses an integral number of sample frames. The buffer size 0N/A * that the system has chosen may be queried by subsequently calling 0N/A * <code>{@link DataLine#getBufferSize}</code>. 0N/A * If this operation succeeds, the line is marked as open, and an 0N/A * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched to the 0N/A * Invoking this method on a line which is already open is illegal 0N/A * and may result in an <code>IllegalStateException</code>. 0N/A * Note that some lines, once closed, cannot be reopened. Attempts 0N/A * to reopen such a line will always result in a 0N/A * <code>LineUnavailableException</code>. 0N/A * @param format the desired audio format 0N/A * @throws LineUnavailableException if the line cannot be 0N/A * opened due to resource restrictions 0N/A * @throws IllegalArgumentException if <code>format</code> 0N/A * is not fully specified or invalid 0N/A * @throws IllegalStateException if the line is already open 0N/A * @throws SecurityException if the line cannot be 0N/A * opened due to security restrictions 0N/A * @see #open(AudioFormat, int) 0N/A * Writes audio data to the mixer via this source data line. The requested 0N/A * number of bytes of data are read from the specified array, 0N/A * starting at the given offset into the array, and written to the data 0N/A * line's buffer. If the caller attempts to write more data than can 0N/A * currently be written (see <code>{@link DataLine#available available}</code>), 0N/A * this method blocks until the requested amount of data has been written. 0N/A * This applies even if the requested amount of data to write is greater 0N/A * than the data line's buffer size. However, if the data line is closed, 0N/A * stopped, or flushed before the requested amount has been written, 0N/A * the method no longer blocks, but returns the number of bytes 0N/A * The number of bytes that can be written without blocking can be ascertained 0N/A * using the <code>{@link DataLine#available available}</code> method of the 0N/A * <code>DataLine</code> interface. (While it is guaranteed that 0N/A * this number of bytes can be written without blocking, there is no guarantee 0N/A * that attempts to write additional data will block.) 0N/A * The number of bytes to write must represent an integral number of 0N/A * sample frames, such that: 0N/A * <center><code>[ bytes written ] % [frame size in bytes ] == 0</code></center> 0N/A * The return value will always meet this requirement. A request to write a 0N/A * number of bytes representing a non-integral number of sample frames cannot 0N/A * be fulfilled and may result in an <code>IllegalArgumentException</code>. 0N/A * @param b a byte array containing data to be written to the data line 0N/A * @param len the length, in bytes, of the valid data in the array 0N/A * (in other words, the requested amount of data to write, in bytes) 0N/A * @param off the offset from the beginning of the array, in bytes 0N/A * @return the number of bytes actually written 0N/A * @throws IllegalArgumentException if the requested number of bytes does 0N/A * not represent an integral number of sample frames, 0N/A * or if <code>len</code> is negative 0N/A * @throws ArrayIndexOutOfBoundsException if <code>off</code> is negative, 0N/A * or <code>off+len</code> is greater than the length of the array 0N/A * @see TargetDataLine#read 0N/A * @see DataLine#available 0N/A * Obtains the number of sample frames of audio data that can be written to 0N/A * the mixer, via this data line, without blocking. Note that the return 0N/A * value measures sample frames, not bytes. 0N/A * @return the number of sample frames currently available for writing 0N/A * @see TargetDataLine#availableRead 0N/A //public int availableWrite();