javax.microedition.amms.control.camera
Interface SnapshotControl

All Superinterfaces:

javax.microedition.media.Control

public interface SnapshotControl
extends javax.microedition.media.Control

SnapshotControl controls burst shooting with the camera. With this Control, it is possible to shoot multiple pictures with one method call in an efficient way.

SnapshotControl stores the captured pictures in the file system. Initially, before any setDirectory method calls the storage directory is pointing to the default image store location of the implementing platform. That directory can be queried by getDirectory before setting a new directory.

Images will be stored in the files system only if the application has rights to create files to the given directory. Rights are checked when the setDirectory method is called but it is possible that the rights are changed after that. In that case, a STORAGE_ERROR event will be posted if the application has no file creation rights when an attempt is made to store the captured image in the file system.

The structure of the generated file name is <prefix><auto generated string><suffix>

where

• prefix is a user given prefix String.
• auto generated string is a String generated automatically by the implementation. The generated String is a zero padded four digit running number starting from 0. Therefore, the sequence of generated Strings is "0000", "0001", "0002" etc. The length of the String increases if more digits are needed to represent the number so "9999" will be followed by "10000".
• suffix is a user given suffix String. Wanted file extension, like ".jpg", is part of the suffix.

File name generation runs through the lifetime of the Player. In other words, it is not necessary to set the prefix before each call of the start method. Notice that it is likely that the naming method defined here differs from the naming system of the native imaging applications of the device.

If the directory, where the files are stored, contains a file with the same name as the generated image file, the generated image file will not be written anywhere. A STORAGE_ERROR message with a the name of the file, whose writing failed, will be sent and capturing of the images will stop.

Changing directory, prefix and suffix are effective when start is called. On-going burst shooting is not affected.

Format of the stored pictures is set by ImageFormatControl. The default format is JPEG if it's supported.

Field Summary

static int	FREEZE Takes one snapshot, freezes the viewfinder, and unfreezes it again after some time.
static int	FREEZE_AND_CONFIRM Freezes the viewfinder and keeps it frozen until unfreeze is called.
static java.lang.String	SHOOTING_STOPPED Posted to PlayerListener when the burst shooting stops and the files have been stored into the file system.
static java.lang.String	STORAGE_ERROR Posted to PlayerListener when there has been an error while storing the files into the file system.
static java.lang.String	WAITING_UNFREEZE Posted to PlayerListener when shooting has been started as FREEZE_AND_CONFIRM.

Method Summary

java.lang.String	getDirectory() Gets the storage directory.
java.lang.String	getFilePrefix() Gets the filename prefix.
java.lang.String	getFileSuffix() Gets the filename suffix.
void	setDirectory(java.lang.String directory) Sets the file directory where the images will be stored.
void	setFilePrefix(java.lang.String prefix) Sets the filename prefix.
void	setFileSuffix(java.lang.String suffix) Sets the filename suffix.
void	start(int maxShots) Starts burst shooting.
void	stop() Stops burst shooting.
void	unfreeze(boolean save) Unfreezes the viewfinder and saves the snapshot depending on the parameter.

Field Detail

SHOOTING_STOPPED

static final java.lang.String SHOOTING_STOPPED

Posted to PlayerListener when the burst shooting stops and the files have been stored into the file system. When this event is received, the eventData parameter is a String containing the name of the last generated file.

Value SHOOTING_STOPPED is assigned to SHOOTING_STOPPED.

See Also:

Constant Field Values

STORAGE_ERROR

static final java.lang.String STORAGE_ERROR

Posted to PlayerListener when there has been an error while storing the files into the file system. Shooting of the images is stopped but SHOOTING_STOPPED event will not be posted. When this event is received, the eventData parameter is a String containing the name of the file whose writing failed.

Value STORAGE_ERROR is assigned to STORAGE_ERROR.

See Also:

Constant Field Values

WAITING_UNFREEZE

static final java.lang.String WAITING_UNFREEZE

Posted to PlayerListener when shooting has been started as FREEZE_AND_CONFIRM. At this point, the implementation is waiting that unfreeze will be called. If the application is waiting for the user to choose whether the picture should be saved or not, the query should be done in a separate thread and this method should return as quickly as possible.

When this event is received, the eventData parameter will be null.

Value WAITING_UNFREEZE is assigned to WAITING_UNFREEZE.

See Also:

Constant Field Values

FREEZE

static final int FREEZE

Takes one snapshot, freezes the viewfinder, and unfreezes it again after some time. The time the viewfinder is frozen is in the range of seconds and the exact time is implementation specific.

See Also:

Constant Field Values

FREEZE_AND_CONFIRM

static final int FREEZE_AND_CONFIRM

Freezes the viewfinder and keeps it frozen until unfreeze is called. Takes a snapshot depending on the parameter of the unfreeze method.

See Also:

unfreeze(boolean), Constant Field Values

Method Detail

setDirectory

void setDirectory(java.lang.String directory)

Sets the file directory where the images will be stored.

The directory name is given as a String which can contain the trailing slash "/" in the directory name but it is not required.

For example, both "/SDCard/" and "/SDCard" set the directory to the root of the SDCard in a platform implementing FileConnection of JSR-75. In case of FileConnection of JSR-75 the return value of FileConnection.getPath() can be used as it is as a parameter for this method.

New directory is effective when start is called. Directory for on-going burst shooting is not changed.

Parameters:

directory - the storage directory

Throws:

java.lang.IllegalArgumentException - if the given directory does not exist or it is null

java.lang.SecurityException - if the creation of files to the given location is not allowed

getDirectory

java.lang.String getDirectory()

Gets the storage directory. If setDirectory has not been called the directory points to the default image storing location.

Returns:

the current storage directory with the trailing slash "/"

setFilePrefix

void setFilePrefix(java.lang.String prefix)

Sets the filename prefix.

New prefix is effective when start is called. Prefix for on-going burst shooting is not changed.

Parameters:

prefix - the prefix String for the files to be created

Throws:

java.lang.IllegalArgumentException - if the given prefix cannot be set or if it is null

getFilePrefix

java.lang.String getFilePrefix()

Gets the filename prefix.

Returns:

the filename prefix

setFileSuffix

void setFileSuffix(java.lang.String suffix)

Sets the filename suffix.

New suffix is effective when start is called. Suffix for on-going burst shooting is not changed.

Throws:

java.lang.IllegalArgumentException - if the given suffix cannot be set or if it is null

getFileSuffix

java.lang.String getFileSuffix()

Gets the filename suffix.

Returns:

the filename suffix

start

void start(int maxShots)
           throws java.lang.SecurityException

Starts burst shooting.

Parameters:

maxShots - the maximum number of shots that are going to be taken or FREEZE or FREEZE_AND_CONFIRM. Integer.MAX_VALUE will take as many shots as possible. Calling the method overrides the previous call when burst shooting is going on.

Throws:

java.lang.IllegalArgumentException - if maxShots is less than one, and not FREEZE or FREEZE_AND_CONFIRM.

java.lang.IllegalStateException - if prefix and suffix have not been set or the Player is not in STARTED state.

java.lang.SecurityException - if the application does not have permission to take snapshots

stop

void stop()

Stops burst shooting.

unfreeze

void unfreeze(boolean save)

Unfreezes the viewfinder and saves the snapshot depending on the parameter. The method does not do anything if start(FREEZE_AND_CONFIRM) has not been called.

Parameters:

save - true to save the snapshot, false not to save the snapshot (and not to post the SHOOTING_STOPPED event)