001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.media.control;
027:
028: import java.io.IOException;
029: import java.io.OutputStream;
030: import javax.microedition.media.MediaException;
031:
032: /**
033: * <code>RecordControl</code> controls the recording of media
034: * from a <code>Player</code>. <code>RecordControl</code> records
035: * what's currently being played by the <code>Player</code>.
036: * <p>
037: * <h2>Example</h2>
038: * <blockquote>
039: * <pre>
040: * try {
041: * // Create a Player that captures live audio.
042: * Player p = Manager.createPlayer("capture://audio");
043: * p.realize();
044: * // Get the RecordControl, set the record stream,
045: * // start the Player and record for 5 seconds.
046: * RecordControl rc = (RecordControl)p.getControl("RecordControl");
047: * ByteArrayOutputStream output = new ByteArrayOutputStream();
048: * rc.setRecordStream(output);
049: * rc.startRecord();
050: * p.start();
051: * Thread.currentThread().sleep(5000);
052: * rc.commit();
053: * p.close();
054: * } catch (IOException ioe) {
055: * } catch (MediaException me) {
056: * } catch (InterruptedException ie) { }
057: * </pre>
058: * </blockquote>
059: *
060: * @see javax.microedition.media.Player
061: */
062: public interface RecordControl extends javax.microedition.media.Control {
063:
064: /**
065: * Set the output stream where the data will be
066: * recorded.
067: * <p>
068: * Whenever possible, the recording format is the same as the format
069: * of the input media. In some cases, the recording format may be
070: * different from the input format if the input format is not a
071: * recordable format, e.g. streaming media data. An application
072: * can query the recorded format by calling the
073: * <code>getContentType</code> method.
074: *
075: * @param stream The output stream where the data will be recorded.
076: * @exception IllegalStateException Thrown if one of the following
077: * conditions is true:
078: * <ul>
079: * <li>
080: * <code>startRecord</code> has been called and <code>commit</code> has
081: * not been called.
082: * <li>
083: * <code>setRecordLocation</code> has been called and <code>commit</code> has
084: * not been called.
085: * </ul>
086: *
087: * @exception IllegalArgumentException Thrown if
088: * <code>stream</code> is null.
089: * @exception SecurityException Thrown if the caller does not
090: * have security permission to set the record stream.
091: */
092: void setRecordStream(OutputStream stream);
093:
094: /**
095: * Set the output location where the data will be recorded.
096: * <p>
097: * Whenever possible, the recording format is the same as the format
098: * of the input media. In some cases, the recording format may be
099: * different from the input format if the input format is not a
100: * recordable format, e.g. streaming media data. An application
101: * can query the recorded format by calling the
102: * <code>getContentType</code> method.
103: *
104: * @param locator The locator specifying where the
105: * recorded media will be saved. The locator must be
106: * specified as a URL.
107: * @exception IllegalStateException Thrown if one of the following
108: * conditions is true:
109: * <ul>
110: * <li>
111: * <code>startRecord</code> has been called and <code>commit</code> has
112: * not been called.
113: * <li>
114: * <code>setRecordStream</code> has been called and <code>commit</code> has
115: * not been called.
116: * </ul>
117: * @exception IllegalArgumentException Thrown if <code>locator</code>
118: * is null.
119: * @exception IOException Thrown if protocol is valid but the
120: * media cannot be created at the specified location.
121: * @exception MediaException Thrown if the locator is not in URL syntax
122: * or it specifies a protocol that is not supported.
123: * @exception SecurityException Thrown if the caller does not
124: * have security permission to set the record location.
125: */
126: void setRecordLocation(String locator) throws IOException,
127: MediaException;
128:
129: /**
130: * Return the content type of the recorded media.
131: *
132: * The content type is given in the
133: * <a HREF="../Manager.html#content-type">content type syntax</a>.
134: *
135: * @return The content type of the media.
136: */
137: String getContentType();
138:
139: /**
140: * Start recording the media.
141: * <p>
142: * If the <code>Player</code> is already started, <code>startRecord</code>
143: * will immediately start the recording. If the <code>Player</code>
144: * is not already started, <code>startRecord</code> will not
145: * record any media. It will put the recording in a "standby" mode.
146: * As soon as the <code>Player</code> is started,
147: * the recording will start right away.
148: * <p>
149: * If <code>startRecord</code> is called when the recording has
150: * already started, it will be ignored.
151: * <p>
152: * When <code>startRecord</code> returns, the recording has started
153: * and a <i>RECORD_STARTED</i> event will be delivered through the
154: * <code>PlayerListener</code>.
155: * <p>
156: * If an error occurs while recording is in progress,
157: * <i>RECORD_ERROR</i> event will be delivered via the PlayerListener.
158: *
159: * @exception IllegalStateException Thrown if any of the following
160: * conditions is true:
161: * <ul>
162: * <li>
163: * if <code>setRecordLocation</code> or <code>setRecordStream</code> has
164: * not been called for the first time.
165: * <li>
166: * If <code>commit</code> has been called and
167: * <code>setRecordLocation</code> or <code>setRecordStream</code>
168: * has not been called.
169: * </ul>
170: */
171: void startRecord();
172:
173: /**
174: * Stop recording the media. <code>stopRecord</code> will not
175: * automatically stop the <code>Player</code>. It only stops
176: * the recording.
177: * <p>
178: * Stopping the <code>Player</code> does not imply
179: * a <code>stopRecord</code>. Rather, the recording
180: * will be put into a "standby" mode. Once the <code>Player</code>
181: * is re-started, the recording will resume automatically.
182: * <p>
183: * After <code>stopRecord</code>, <code>startRecord</code> can
184: * be called to resume the recording.
185: * <p>
186: * If <code>stopRecord</code> is called when the recording has
187: * already stopped, it will be ignored.
188: * <p>
189: * When <code>stopRecord</code> returns, the recording has stopped
190: * and a <i>RECORD_STOPPED</i> event will be delivered through the
191: * <code>PlayerListener</code>.
192: */
193: void stopRecord();
194:
195: /**
196: * Complete the current recording.
197: * <p>
198: * If the recording is in progress, <code>commit</code>
199: * will implicitly call <code>stopRecord</code>.
200: * <p>
201: * To record again after <code>commit</code> has been called,
202: * <code>setRecordLocation</code> or <code>setRecordStream</code>
203: * must be called.
204: *
205: * @exception IOException Thrown if an I/O error occurs during commit.
206: * The current recording is not valid. To record again,
207: * <code>setRecordLocation</code> or <code>setRecordStream</code>
208: * must be called.
209: *
210: */
211: void commit() throws IOException;
212:
213: /**
214: * Set the record size limit. This limits the size of the
215: * recorded media to the number of bytes specified.
216: * <p>
217: * When recording is in progress, <code>commit</code> will be
218: * called implicitly in the following cases:
219: * <ul>
220: * <li>
221: * Record size limit is reached
222: * <li>
223: * If the requested size is less than the already recorded size
224: * <li>
225: * No more space is available.
226: * </ul>
227: * <p>
228: * Once a record size limit has been set, it will remain so
229: * for future recordings until it is changed by another
230: * <code>setRecordSizeLimit</code> call.
231: * <p>
232: * To remove the record size limit, set it to
233: * <code>Integer.MAX_VALUE</code>.
234: * By default, the record size limit is not set.
235: * <p>
236: * Only positive values can be set. Zero or negative values
237: * are invalid and an <code>IllegalArgumentException</code>
238: * will be thrown.
239: *
240: * @param size The record size limit in number of bytes.
241: * @return The actual size limit set.
242: * @exception IllegalArgumentException Thrown if the given size
243: * is invalid.
244: * @exception MediaException Thrown if setting the record
245: * size limit is not supported.
246: */
247: int setRecordSizeLimit(int size) throws MediaException;
248:
249: /**
250: * Erase the current recording.
251: * <p>
252: * If the recording is in progress, <code>reset</code>
253: * will implicitly call <code>stopRecord</code>.
254: * <p>
255: * Calling <code>reset</code> after <code>commit</code>
256: * will have no effect on the current recording.
257: * <p>
258: * If the <code>Player</code> that is associated with this
259: * <code>RecordControl</code> is closed, <code>reset</code>
260: * will be called implicitly.
261: *
262: * @exception IOException Thrown if the current recording
263: * cannot be erased. The current recording is not valid.
264: * To record again, <code>setRecordLocation</code> or
265: * <code>setRecordStream</code> must be called.
266: *
267: */
268: void reset() throws IOException;
269: }
|