Use is subject to License Terms. Your use of this web site or any of its contents or software indicates your agreement to be bound by these License Terms.

Copyright © 2002-2006 Sun Microsystems, Inc.; Nokia Corporation. All rights reserved. See the Copyright Notice and Specification License for more details.

javax.microedition.media.control
Interface RecordControl

All Superinterfaces:

Control

public interface RecordControl
extends Control

RecordControl controls the recording of media from a Player. RecordControl records what's currently being played by the Player.

Example

 try {
    // Create a Player that captures live audio.
    Player p = Manager.createPlayer("capture://audio");
    p.realize();
    // Get the RecordControl, set the record stream,
    // start the Player and record for 5 seconds.
    RecordControl rc = (RecordControl)p.getControl("RecordControl");
    ByteArrayOutputStream output = new ByteArrayOutputStream();
    rc.setRecordStream(output);
    rc.startRecord();
    p.start();
    Thread.currentThread().sleep(5000);
    rc.commit();
    p.close();
 } catch (IOException ioe) {
 } catch (MediaException me) {
 } catch (InterruptedException ie) { }
 

See Also:

Player

Method Summary

void	commit() Complete the current recording.
java.lang.String	getContentType() Return the content type of the recorded media.
void	reset() Erase the current recording.
void	setRecordLocation(java.lang.String locator) Set the output location where the data will be recorded.
int	setRecordSizeLimit(int size) Set the record size limit.
void	setRecordStream(java.io.OutputStream stream) Set the output stream where the data will be recorded.
void	startRecord() Start recording the media.
void	stopRecord() Stop recording the media.

Method Detail

setRecordStream

void setRecordStream(java.io.OutputStream stream)

Set the output stream where the data will be recorded.

Whenever possible, the recording format is the same as the format of the input media. In some cases, the recording format may be different from the input format if the input format is not a recordable format, e.g. streaming media data. An application can query the recorded format by calling the getContentType method.

Parameters:

stream - The output stream where the data will be recorded.

Throws:

java.lang.IllegalStateException - Thrown if one of the following conditions is true:

• startRecord has been called and commit has not been called.
• setRecordLocation has been called and commit has not been called.

java.lang.IllegalArgumentException - Thrown if stream is null.

java.lang.SecurityException - Thrown if the caller does not have security permission to set the record stream.

setRecordLocation

void setRecordLocation(java.lang.String locator)
                       throws java.io.IOException,
                              MediaException

Set the output location where the data will be recorded.

Whenever possible, the recording format is the same as the format of the input media. In some cases, the recording format may be different from the input format if the input format is not a recordable format, e.g. streaming media data. An application can query the recorded format by calling the getContentType method.

Parameters:

locator - The locator specifying where the recorded media will be saved. The locator must be specified as a URL.

Throws:

java.lang.IllegalStateException - Thrown if one of the following conditions is true:

• startRecord has been called and commit has not been called.
• setRecordStream has been called and commit has not been called.

java.lang.IllegalArgumentException - Thrown if locator is null.

java.io.IOException - Thrown if protocol is valid but the media cannot be created at the specified location.

MediaException - Thrown if the locator is not in URL syntax or it specifies a protocol that is not supported.

java.lang.SecurityException - Thrown if the caller does not have security permission to set the record location.

getContentType

java.lang.String getContentType()

Return the content type of the recorded media. The content type is given in the content type syntax.

Returns:

The content type of the media.

startRecord

void startRecord()

Start recording the media.

If the Player is already started, startRecord will immediately start the recording. If the Player is not already started, startRecord will not record any media. It will put the recording in a "standby" mode. As soon as the Player is started, the recording will start right away.

If startRecord is called when the recording has already started, it will be ignored.

When startRecord returns, the recording has started and a RECORD_STARTED event will be delivered through the PlayerListener.

If an error occurs while recording is in progress, RECORD_ERROR event will be delivered via the PlayerListener.

Throws:

java.lang.IllegalStateException - Thrown if any of the following conditions is true:

• if setRecordLocation or setRecordStream has not been called for the first time.
• If commit has been called and setRecordLocation or setRecordStream has not been called.

stopRecord

void stopRecord()

Stop recording the media. stopRecord will not automatically stop the Player. It only stops the recording.

Stopping the Player does not imply a stopRecord. Rather, the recording will be put into a "standby" mode. Once the Player is re-started, the recording will resume automatically.

After stopRecord, startRecord can be called to resume the recording.

If stopRecord is called when the recording has already stopped, it will be ignored.

When stopRecord returns, the recording has stopped and a RECORD_STOPPED event will be delivered through the PlayerListener.

commit

void commit()
            throws java.io.IOException

Complete the current recording.

If the recording is in progress, commit will implicitly call stopRecord.

To record again after commit has been called, setRecordLocation or setRecordStream must be called.

Throws:

java.io.IOException - Thrown if an I/O error occurs during commit. The current recording is not valid. To record again, setRecordLocation or setRecordStream must be called.

setRecordSizeLimit

int setRecordSizeLimit(int size)
                       throws MediaException

Set the record size limit. This limits the size of the recorded media to the number of bytes specified.

When recording is in progress, commit will be called implicitly in the following cases:

• Record size limit is reached
• If the requested size is less than the already recorded size
• No more space is available.

Once a record size limit has been set, it will remain so for future recordings until it is changed by another setRecordSizeLimit call.

To remove the record size limit, set it to Integer.MAX_VALUE. By default, the record size limit is not set.

Only positive values can be set. Zero or negative values are invalid and an IllegalArgumentException will be thrown.

Parameters:

size - The record size limit in number of bytes.

Returns:

The actual size limit set.

Throws:

java.lang.IllegalArgumentException - Thrown if the given size is invalid.

MediaException - Thrown if setting the record size limit is not supported.

reset

void reset()
           throws java.io.IOException

Erase the current recording.

If the recording is in progress, reset will implicitly call stopRecord.

Calling reset after commit will have no effect on the current recording.

If the Player that is associated with this RecordControl is closed, reset will be called implicitly.

Throws:

java.io.IOException - Thrown if the current recording cannot be erased. The current recording is not valid. To record again, setRecordLocation or setRecordStream must be called.