/*
*
* Copyright 1990-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
package javax.microedition.media.control;
/**
* <code>MetaDataControl</code> is used to retrieve metadata information
* included within the media streams. A <code>MetaDataControl</code>
* object recognizes and stores metadata and provides XML-like accessor
* methods to retrieve this information.
* <br>
* Predefined keys are provided to refer to commonly used metadata fields
* (title, copyright, data, author).
*/
public interface MetaDataControl extends javax.microedition.media.Control {
/**
* Default key for AUTHOR information.
* <p>
* Value "author" is assigned to <code>AUTHOR_KEY</code>.
*/
String AUTHOR_KEY = "author";
/**
* Default key for COPYRIGHT information.
* <p>
* Value "copyright" is assigned to <code>COPYRIGHT_KEY</code>.
*/
String COPYRIGHT_KEY = "copyright";
/**
* Default key for DATE information.
* <p>
* Value "date" is assigned to <code>DATE_KEY</code>.
*/
String DATE_KEY = "date";
/**
* Default key for TITLE information.
* <p>
* Value "title" is assigned to <code>TITLE_KEY</code>.
*/
String TITLE_KEY = "title";
/**
* Return the list of keys for the available metadata values.
* The returned array must be an array with at least one
* key.
*
* @return The list of keys for the available metadata values.
*/
String[] getKeys();
/**
* Retrieve the value found in the metadata associated with the
* given key. Only keys obtained from <code>getKeys</code>
* are valid and can be used to retrieve metadata values.
* If <code>null</code> or an invalid key is used, an
* <code>IllegalArgumentException</code> will be thrown.
* <p>
* Some keys are valid but the associated metadata may not
* be available before a certain portion of the media is
* played. For example, some streaming media types may
* contain metadata that's stored at the end of the file.
* As a result, the metadata may not be available
* until the playback reaches the end of media. When
* that happens, calling <code>getKeyValues</code> with
* those keys will return <code>null</code> before the
* data is available. However, when the playback reaches
* the end of media, all metadata values must be
* made available.
*
* @param key a key to retrieve the value.
* @return the value of the key or null if the given key is valid but
* the value is not yet available.
* @exception IllegalArgumentException Thrown if the given key is
* <code>null</code> or invalid.
*/
String getKeyValue(String key);
}