/*

* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  PlugIn used to extend mma

*

*/

package com.nokia.microedition.media;

import java.io.IOException;

import javax.microedition.media.protocol.DataSource;

import javax.microedition.media.MediaException;

/**

 * This interface can be used extend Mobile Media API. This interface must

 * be registered to <code>ManagerImpl</code> with <code>addPlugIn</code>

 * method. <code>ManagerImpl</code> instance can be obtained with

 * <code>ManagerImpl.getInstance</code> method.

 * <code>getSupportedContentTypes</code> and <code>getSupportedProtocols</code>

 * methods will be called when equivalent Manager methods are called.

 *

 * @see ManagerImpl.addPlugin

 */

public interface PlugIn

{

    /**

     * Return the list of supported content types for the given protocol.

     * <p>

     * See <a href="#content-type">content types</a> for the syntax

     * of the content types returned.

     * See <a href="#media-protocol">protocol name</a> for the syntax

     * of the protocol used.

     * <p>

     * For example, if the given <code>protocol</code>

     * is <code>"http"</code>,

     * then the supported content types that can be played back

     * with the <code>http</code> protocol will be returned.

     * <p>

     * If <code>null</code> is passed in as the <code>protocol</code>,

     * all the supported content types for this implementation

     * will be returned.  The returned array must be non-empty.

     * <p>

     * If the given <code>protocol</code> is an invalid or

     * unsupported protocol, then an empty array will be returned.

     *

     * @param aProtocol The input protocol for the supported content types.

     * @return The list of supported content types for the given protocol.

     */

    String[] getSupportedContentTypes(String aProtocol);

    /**

     * Return the list of supported protocols given the content

     * type.  The protocols are returned

     * as strings which identify what locators can be used for creating

     * <code>Player</code>'s.

     * <p>

     * See <a href="#media-protocol">protocol name</a> for the syntax

     * of the protocols returned.

     * See <a href="#content-type">content types</a> for the syntax

     * of the content type used.

     * <p>

     * For example, if the given <code>content_type</code>

     * is <code>"audio/x-wav"</code>, then the supported protocols

     * that can be used to play back <code>audio/x-wav</code>

     * will be returned.

     * <p>

     * If <code>null</code> is passed in as the

     * <code>content_type</code>,

     * all the supported protocols for this implementation

     * will be returned.  The returned array must be non-empty.

     * <p>

     * If the given <code>content_type</code> is an invalid or

     * unsupported content type, then an empty array will be returned.

     *

     * @param aContentType The content type for the supported protocols.

     * @return The list of supported protocols for the given content type.

     */

    String[] getSupportedProtocols(String aContentType);

    /**

     * Create a <code>Player</code> for a <code>DataSource</code>.

     * This method will be called if MMA was not able to create

     * Player for the DataSource.

     *

     * @param aDataSource The <CODE>DataSource</CODE> that provides

     * the media content.

     * @return A new <code>Player</code>.

     * @exception IllegalArgumentException Thrown if <code>source</code>

     * is <code>null</code>.

     * @exception MediaException Thrown if a <code>Player</code> cannot

     * be created for the given <code>DataSource</code>.

     * @exception IOException Thrown if there was a problem connecting

     * with the source.

     * @exception SecurityException Thrown if the caller does not

     * have security permission to create the <code>Player</code>.

     */

    InternalPlayer createPlayer(DataSource aDataSource)

    throws MediaException, IOException;

    /**

     * Method used to prepare player. This method is used only for

     * MMA internal extensions. If PlugIn does not support given player

     * this method must not do anything.

     *

     * @param aPlayer Player to prepare.

     * @exception MediaException Thrown if a <code>InternalPlayer</code> cannot

     * be prepared.

     */

    void preparePlayer(InternalPlayer aPlayer) throws MediaException;

}