javax.microedition.amms.control
Interface FormatControl

All Superinterfaces:
Control
All Known Subinterfaces:
AudioFormatControl, ContainerFormatControl, ImageFormatControl, VideoFormatControl

public interface FormatControl
extends Control

FormatControl controls the format used for storing media.

Formats are specified when media is captured from a Player or if the format is changed when media is processed by a MediaProcessor. FormatControl is a super interface for ContainerFormatControl, ImageFormatControl, AudioFormatControl and VideoFormatControl. FormatControl specifies the methods to set and get various parameters to specify the media format.

The purpose of the the different format Controls is as follows:

Formats

The format is set by the FormatControl.setFormat(String) method which takes one of the formats returned by the FormatControl.getSupportedFormats() as a parameter. Formats are represented as MIME types. MIME type alone does not provide enough information to specify the format exactly. Once the format has been set by FormatControl.setFormat(String), FormatControl.PARAM_VERSION_TYPE parameter can be used with FormatControl.setParameter(String, String) (see the next section for details) to set the format exactly to the one that is wanted.

FormatControl.PARAM_VERSION_TYPE definitions are not part of this specification. Instead, a list of definitions can be downloaded from Forum Nokia. The list will be constantly updated and new types will be added as needed.

Parameters

The parameter interface allows various content type specific parameters to be accessed. Supported integer parameters are queried by FormatControl.getSupportedIntParameters() and supported String parameters by FormatControl.getSupportedStrParameters(), respectively. The range of integer values to be set by FormatControl.setParameter(String, int) can be queried by FormatControl.getSupportedIntParameterRange(String). Different values for String parameters to be set by FormatControl.setParameter(String, String) can be queried by FormatControl.getSupportedStrParameterValues(String).

Metadata

Some formats can contain metadata that can be set by FormatControl.setMetadata(String, String). FormatControl.getMetadataSupportMode() tells what kind of metadata can be set to the media and FormatControl.getSupportedMetadataKeys() returns a list of the metadata keys or, in case any metadata keys can be used, a list of the most common ones. Some metadata might be added to the content by the implementation. For instance, images taken by the digital camera may automatically contain information about resolution, camera settings and time when the image was taken.

Occasionally, when the MediaProcessor is used it is possible that the metadata is at the end of the processed stream and it is not known before the processing is started. This could result into contradiction between the metadata set by the application and the metadata already in the media. FormatControl.setMetadataOverride(boolean) can be used to tell if the new metadata should override the existing metadata or vice versa.

See MetaDataControl in JSR-135 for reading metadata.

Example

This example illustrates how to set a format and some parameters for it. Here, p is Player for camera. See Overview for the complete example.
     //Set up snapshot format:
    imageFormatControl = (ImageFormatControl)
      p.getControl("javax.microedition.amms.control.ImageFormatControl");
    if(imageFormatControl != null) {
      imageFormatControl.setFormat("image/jpeg");
      imageFormatControl.setParameter(FormatControl.PARAM_VERSION_TYPE,
                                      "JPEG");
      //JPEG quality:
      imageFormatControl.setParameter(FormatControl.PARAM_QUALITY, 80);
    }
 
Adding metadata to the image can be done as follows:
         imageFormatControl.setMetadata("Title", "Swimming in summer 2006");
         imageFormatControl.setMetadata("Keywords", "swimming, beach, summer 2006");
         imageFormatControl.setMetadata("Comments", "Warmest day of the whole summer");
 

Since:
BlackBerry API 5.0.0

Field Summary
static int METADATA_NOT_SUPPORTED
          Setting metadata is not supported.
static int METADATA_SUPPORTED_FIXED_KEYS
          Setting metadata is supported and the set of metadata keys is limited.
static int METADATA_SUPPORTED_FREE_KEYS
          Setting metadata is supported and any Strings can be used as metadata keys.
static String PARAM_BITRATE
          The output bit rate integer parameter.
static String PARAM_BITRATE_TYPE
          The bit rate type String parameter tells if the bit rate is constant or variable.
static String PARAM_FRAMERATE
          The output frame rate integer parameter.
static String PARAM_QUALITY
          The quality parameter for example for JPEG.
static String PARAM_SAMPLERATE
          The output sample rate integer parameter.
static String PARAM_VERSION_TYPE
          The format version type String parameter to specify what is the the type of the format.
 
Method Summary
 int getEstimatedBitRate()
          Gets the estimated bit rate of the media.
 String getFormat()
          Get the format.
 int getIntParameterValue(String parameter)
          Gets the current value of an integer parameter.
 boolean getMetadataOverride()
          Returns the metadata override mode.
 int getMetadataSupportMode()
          Returns the metadata support mode.
 String getStrParameterValue(String parameter)
          Gets the current value of a String parameter.
 String[] getSupportedFormats()
          Gets supported formats.
 int[] getSupportedIntParameterRange(String parameter)
          Gets range for the given int-valued parameter.
 String[] getSupportedIntParameters()
          Gets the supported parameters for the current format.
 String[] getSupportedMetadataKeys()
          Returns a list of supported metadata keys.
 String[] getSupportedStrParameterValues(String parameter)
          Gets available values for the given String-valued parameter.
 String[] getSupportedStrParameters()
          Gets the supported parameters for the current format.
 void setFormat(String format)
          Sets the format.
 void setMetadata(String key, String value)
          Sets metadata for the media
 void setMetadataOverride(boolean override)
          Sets the metadata override mode.
 int setParameter(String parameter, int value)
          Sets int-valued parameter's value.
 void setParameter(String parameter, String value)
          Sets String-valued parameter's value.
 



Field Detail

METADATA_NOT_SUPPORTED

static final int METADATA_NOT_SUPPORTED
Setting metadata is not supported.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

METADATA_SUPPORTED_FIXED_KEYS

static final int METADATA_SUPPORTED_FIXED_KEYS
Setting metadata is supported and the set of metadata keys is limited.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

METADATA_SUPPORTED_FREE_KEYS

static final int METADATA_SUPPORTED_FREE_KEYS
Setting metadata is supported and any Strings can be used as metadata keys.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PARAM_BITRATE

static final String PARAM_BITRATE
The output bit rate integer parameter. The value of this parameter will be defined in bits per second.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PARAM_BITRATE_TYPE

static final String PARAM_BITRATE_TYPE
The bit rate type String parameter tells if the bit rate is constant or variable. Possible values are "constant" and "variable".

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PARAM_SAMPLERATE

static final String PARAM_SAMPLERATE
The output sample rate integer parameter. The value of this parameter will be defined in samples per second.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PARAM_FRAMERATE

static final String PARAM_FRAMERATE
The output frame rate integer parameter. The value of this parameter will be defined in samples per second.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PARAM_QUALITY

static final String PARAM_QUALITY
The quality parameter for example for JPEG. This parameter can be either integer or String.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PARAM_VERSION_TYPE

static final String PARAM_VERSION_TYPE
The format version type String parameter to specify what is the the type of the format.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

getSupportedFormats

String[] getSupportedFormats()
Gets supported formats.

Returns:
an array of supported formats
Since:
BlackBerry API 5.0.0

getSupportedStrParameters

String[] getSupportedStrParameters()
Gets the supported parameters for the current format.

Returns:
an array of supported String-valued parameters
Since:
BlackBerry API 5.0.0

getSupportedIntParameters

String[] getSupportedIntParameters()
Gets the supported parameters for the current format.

Returns:
an array of supported int-valued parameters
Since:
BlackBerry API 5.0.0

getSupportedStrParameterValues

String[] getSupportedStrParameterValues(String parameter)
Gets available values for the given String-valued parameter.

Parameters:
parameter - the parameter whose valid values are queried
Returns:
an array of supported values for the given parameter
Throws:
IllegalArgumentException - if the parameter is not supported or if it is null
Since:
BlackBerry API 5.0.0

getSupportedIntParameterRange

int[] getSupportedIntParameterRange(String parameter)
Gets range for the given int-valued parameter.

Parameters:
parameter - the parameter whose range is queried
Returns:
min and max value for the given parameter
Throws:
IllegalArgumentException - if the parameter is not supported or if it is null
Since:
BlackBerry API 5.0.0

setFormat

void setFormat(String format)
Sets the format.

Parameters:
format - the new format
Throws:
IllegalArgumentException - if the format is not supported or if it is null
Since:
BlackBerry API 5.0.0

getFormat

String getFormat()
Get the format.

Returns:
the current format
Since:
BlackBerry API 5.0.0

setParameter

int setParameter(String parameter,
                 int value)
Sets int-valued parameter's value.

Parameters:
parameter - the parameter to be set
value - the new value to be set
Returns:
the value that was set
Throws:
IllegalArgumentException - if the parameter is not supported or the value for the supported parameter is not supported or if the parameter is null
Since:
BlackBerry API 5.0.0

setParameter

void setParameter(String parameter,
                  String value)
Sets String-valued parameter's value.

Parameters:
parameter - the parameter to be set
value - the new value to be set
Throws:
IllegalArgumentException - if the parameter is not supported or the value for the supported parameter is not supported or if the parameter or value is null
Since:
BlackBerry API 5.0.0

getStrParameterValue

String getStrParameterValue(String parameter)
Gets the current value of a String parameter.

Parameters:
parameter - the parameter whose value is queried
Returns:
the current value of the given parameter
Throws:
IllegalArgumentException - if the parameter is not supported or if it is null
Since:
BlackBerry API 5.0.0

getIntParameterValue

int getIntParameterValue(String parameter)
Gets the current value of an integer parameter.

Parameters:
parameter - the parameter whose value is queried
Returns:
the current value of the given parameter
Throws:
IllegalArgumentException - if the parameter is not supported or if it is null
Since:
BlackBerry API 5.0.0

getEstimatedBitRate

int getEstimatedBitRate()
                        throws MediaException
Gets the estimated bit rate of the media.

Returns:
estimated bit rate in bits/second
Throws:
MediaException - if size estimation is not supported or if the media type is unstreamable
Since:
BlackBerry API 5.0.0

setMetadata

void setMetadata(String key,
                 String value)
                 throws MediaException
Sets metadata for the media

Parameters:
key - metadata key
value - metadata value
Throws:
MediaException - if setting of the metadata is not supported
IllegalArgumentException - if the key or value contains unsupported values or if either is null
Since:
BlackBerry API 5.0.0

getSupportedMetadataKeys

String[] getSupportedMetadataKeys()

Returns a list of supported metadata keys. If any String can be used as a metadata getSupportedMetadataKeys returns a list of the most common metadata keys

Returns:
supported metadata keys or a list of the most common ones
Since:
BlackBerry API 5.0.0

getMetadataSupportMode

int getMetadataSupportMode()
Returns the metadata support mode. The support mode is one of the following:

Returns:
current metadata support mode
Since:
BlackBerry API 5.0.0

setMetadataOverride

void setMetadataOverride(boolean override)
Sets the metadata override mode. In the overried mode, the metadata set by the application overrides the metadata existing in the media when the existing metadata is found out only when the processing of the media is already going on.

By default, the metadata override mode is true.

Parameters:
override - true to make application set metadata to be written on top of the existing metadata, false to preserve the existing metadata
Since:
BlackBerry API 5.0.0

getMetadataOverride

boolean getMetadataOverride()
Returns the metadata override mode.

Returns:
true if the metadata set by the application overrides the existing metadata, false if the existing metadata is preserved
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.