manager.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 619 行 · 第 1/2 页

/*
 *   
 *
 *  Copyright  1990-2007 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;


import java.io.InputStream;
import java.io.IOException;



/**
 * <code>Manager</code> is the access point for obtaining
 * system dependent resources such as <code>Players</code>
 * for multimedia processing.
 * <p>
 *
 * A <a href="Player.html"<code>Player</code></a>
 * is an object used to
 * control and render media that
 * is specific to the
 * <a href="#content-type">content type</a>
 * of the data.
 * <p>
 * <code>Manager</code> provides access to an implementation specific
 * mechanism for constructing <code>Players</code>.
 * <p>
 * For convenience, <code>Manager</code> also provides a simplified
 * method to generate simple tones.
 *
 * <h2>Simple Tone Generation</h2>
 *
 * <blockquote>
 * The
 * <a href="#playTone(int, int, int)">
 * <code>playTone</code></a>
 * function is defined to generate
 * tones.  Given the note and duration, the function will
 * produce the specified tone.
 * </blockquote>
 *
 * <h2>Creating Players</h2>
 * <blockquote>
 *
 * <code>Manager</code> provides three methods to create a
 * <code>Player</code> for playing back media:
 * <ul>
 * <li> Create from a media locator.
 * <li> Create from a <code>DataSource</code>.
 * <li> Create from an <code>InputStream</code>.
 * </ul>
 * The <code>Player</code> returned can be used to control the
 * presentation of the media.
 * <p>
 *
 * The simplest way to create a <code>Player</code> is from a
 * <a href="#media-locator">locator in the URI syntax</a>.
 * Given a locator,
 * <a href="#createPlayer(java.lang.String)">
 * <code>createPlayer</code></a>
 * will create a <code>Player</code> suitable to handle the media
 * identified by the locator.
 * <p>
 * Users can also implement a custom <code>DataSource</code> to
 * handle an application-defined protocol.
 * The custom <code>DataSource</code> can
 * be used to create a <code>Player</code> by using the
 * <a href="#createPlayer(javax.microedition.media.protocol.DataSource)">
 * <code>createPlayer</code></a> method.
 * <p>
 * A third version of
 * <a href="#createPlayer(java.io.InputStream, java.lang.String)">
 * <code>createPlayer</code></a>
 * creates a <code>Player</code> from an
 * <code>InputStream</code>.  This can be used to interface with
 * other Java API's which use <code>InputStreams</code> such as
 * the java.io package.  It should be noted that <code>InputStream</code>
 * does not provide the necessary random seeking functionality.  So
 * a <code>Player</code> created from an <code>InputStream</code> may
 * not support random seeking (ala <code>Player.setMediaTime</code>).
 * </blockquote>
 *
 * <h2>System Time Base</h2>
 *
 * <blockquote>
 * All <code>Players</code> need a <code>TimeBase</code>. Many
 * use a system-wide <code>TimeBase</code>, often based on
 * a time-of-day clock.
 * <code>Manager</code> provides access to the system <code>TimeBase</code>
 * through
 * <a href="#getSystemTimeBase()">
 * <code>getSystemTimeBase</code></a>.
 * </blockquote>
 *
 * <a name="content-type"></a>
 * <h2>Content Types</h2>
 * <blockquote>
 * Content types identify the type of media data.  They are
 * defined to be the registered MIME types
 * (<a href=
 * "http://www.iana.org/assignments/media-types/">
 * http://www.iana.org/assignments/media-types/</a>);
 * plus
 * some user-defined types that generally follow the MIME syntax
 * (<a href="ftp://ftp.isi.edu/in-notes/rfc2045.txt">RFC 2045</a>,
 * <a href="ftp://ftp.isi.edu/in-notes/rfc2046.txt">RFC 2046</a>).
 * <p>
 * For example, here are a few common content types:
 * <ol>
 * <li>Wave audio files: <code>audio/x-wav</code>
 * <li>AU audio files: <code>audio/basic</code>
 * <li>MP3 audio files: <code>audio/mpeg</code>
 * <li>MIDI files: <code>audio/midi</code>
 * <li>Tone sequences: <code>audio/x-tone-seq</code>
 * <li>MPEG video files: <code>video/mpeg</code>
 * </ol>
 * </blockquote>
 *
 * <a name="delivery-protocol"></a>
 * <h2>Data Delivery Protocol</h2>
 * <blockquote>
 * A data delivery protocol specifies how media data is
 * delivered to the media processing systems.  Some common
 * protocols are: local file, disk I/O, HTTP, RTP streaming,
 * live media capture etc.
 * <p>
 * <a href="#media-locator">Media locators</a> are used to
 * identify the delivery protocol
 * (as well as the identifier/name of the media).
 * </blockquote>
 *
 * <a name="media-locator"></a>
 * <h2>Media Locator</h2>
 * <blockquote>
 * <a name="media-protocol"></a>
 * Media locators are specified in
 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI syntax</a>
 * which is defined in the form:
 * <p>
 * &nbsp;&nbsp;&nbsp;&nbsp;&lt;scheme&gt;:&lt;scheme-specific-part&gt;
 * <p>
 * The "scheme" part of the locator string identifies the name
 * of the protocol being used to deliver the data.
 * <p>
 * Some media specific locator syntax are defined below:
 *
 * <a name="live-capture"></a>
 * <h3>1. Locators for Live-media Capture</h3>
 * The locators for capturing live media are defined
 * by the following syntax in
 * <a href="http://www.ietf.org/rfc/rfc2234">Augmented BNF</a> notations:
 * <p>
 * <pre>
 *     "capture://" device [ "?" media_encodings ]
 * </pre>
 * &nbsp;&nbsp;To identify the type or the specific
 * name of the device:<p>
 * <pre>
 *     device       = "audio" / "video" / "audio_video" / dev_name
 *     dev_name     = alphanumeric
 *     alphanumeric = 1*( ALPHA / DIGIT )
 * </pre>
 * The syntax for specifying the media encodings are defined in
 * <a href="Manager.html#media_encodings">Media Encoding Strings</a>.<br>
 *   <br>
 *   &nbsp;&nbsp;&nbsp;&nbsp;Examples:
 *   <br>
 * <pre>
 *     capture://audio  (default audio)
 *     capture://audio?encoding=pcm   (default audio in PCM format)
 *     capture://devmic0?encoding=pcm&rate=11025&bits=16&channels=1
 *             (audio from a specific device--devmic0)
 *     <br>
 *     capture://video  (default video)
 *     capture://video?encoding=gray8&width=160&height=120
 *     capture://devcam0?encoding=rgb888&width=160&height=120&fps=7
 *     <br>
 *     capture://mydev?myattr=123   (custom device with custom param)
 * </pre>
 *
 * <h3>2. Locators for RTP streaming</h3>
 * <a href="http://www.ietf.org/rfc/rfc1889.txt">RTP</a>
 *  is a public standard for streaming media.  The locator
 * syntax for specifying RTP sessions is:
 * <pre>
 *     "rtp://" address [ ":" port ] [ "/" type ]
 * </pre>
 * &nbsp;&nbsp;&nbsp;&nbsp;where:
 * <pre>
 *     address and port defines the RTP session.  The
 *     address and port usage is similar to the host and port
 *     usage as defined in the <a href="http://www.ietf.org/rfc/rfc2396.txt">URI syntax</a>.
 *     <br>
 *     type = "audio" / "video" / "text"
 * </pre>
 *   <br>
 *   &nbsp;&nbsp;&nbsp;&nbsp;Example:
 *   <br>
 * <pre>
 *     rtp://224.1.2.3:12344/audio
 * </pre>
 *
 * <h3>3. Locators for Radio Tuner</h3>
 * To create a <code>Player</code> to tune into a radio program, the
 * following locator syntax is used:
 * <p>
 * <pre>
 *     "capture://radio" [ "?" tuner_params ]
 * </pre>
 * &nbsp;&nbsp;&nbsp;&nbsp;where:
 * <pre>
 *     tuner_params = tuner_param *( "&" tuner_param )
 *     tuner_param  = "f=" freq /
 *                    "mod=" modulation /
 *                    "st=" stereo_mode /
 *                    "id=" program_id /
 *                    "preset=" preset
 *     freq         = megahertz /
 *                    kilohertz /
 *                    hertz
 *     megahertz    = pos_integer "M" /
 *                    pos_integer "." pos_integer "M"
 *     kilohertz    = pos_integer "k" /
 *                    pos_integer "." pos_integer "k"
 *     hertz        = pos_integer
 *     modulation   = "fm" / "am"
 *     stereo_mode  = "mono" / "stereo" / "auto"
 *     program_id   = alpanumeric ; identifies an FM channel by its
 *                                  program service name (PS) delivered
 *                                  via Radio Data System (RDS)**.
 *     preset       = pos_integer ; predefined tuning number
 * </pre>
 *   ** The RDS specification is available from
 *   <a href="http://bsonline.techindex.co.uk">http://bsonline.techindex.co.uk</a>, id BSEN 50067:1998.<br>
 *   <br>
 *   &nbsp;&nbsp;&nbsp;&nbsp;Examples:
 *   <br>
 * <pre>
 *     capture://radio?f=91.9M&st=auto
 *               (91.9 MHz with automatic stereo setting)
 *     capture://radio?f=558k&mod=am
 *               (558 kHz with amplitude modulation)
 *     capture://radio?id=yleq
 *               (FM channel that has "yleq" as its program service name
 *                delivered via Radia Data System)
 * </pre>
 * </blockquote>
 * <p>
 *
 * <a name="media_encodings"></a>
 * <h2>Media Encoding Strings</h2>
 * <blockquote>
 * There are a few places where media encodings are specified
 * as strings, e.g. in the capture media locator.  Sections A to E
 * define the encoding syntax.
 * <a href="#encodings_rules">Section F</a>
 * defines the rules for how they should be handled.
 * <p>
 *
 * &nbsp;&nbsp;A. Describing media encodings:<p>
 * <pre>
 *     media_encodings = audio_encodings /
 *                       video_encodings /
 *                       mixed_encodings /
 *                       custom_encodings
 * </pre>
 *
 * <a name="audio_encodings"></a>
 * &nbsp;&nbsp;B. Describing the audio encodings:<p>
 * <pre>
 *     audio_encodings = audio_enc_param *( "&" audio_param )
 *     audio_enc_param = "encoding=" audio_enc
 *     audio_enc       = "pcm" / "ulaw" / "gsm" / content_type
 *     audio_param     = "rate=" rate /
 *                       "bits=" bits /
 *                       "channels=" channels /
 *                       "endian=" endian /
 *                       "signed=" signed /
 *                       "type=" audio_type
 *     rate            = "96000" / "48000" / "44100" /
 *                       "22050" / "16000" / "11025" /
 *                       "8000" / other_rate
 *     other_rate      = pos_integer
 *     bits            = "8" / "16" / "24" / other_bits
 *     other_bits      = pos_integer
 *     channels        = pos_integer
 *     endian          = "little" / "big"
 *     signed          = "signed" / "unsigned"