001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.media.protocol;
027:
028: import java.io.IOException;
029: import javax.microedition.media.Controllable;
030:
031: /**
032: * Abstracts a single stream of media data. It is used in
033: * conjunction with <code>DataSource</code> to provide the
034: * input interface to a <code>Player</code>
035: * <p>
036: * SourceStream may provide type-specific controls. For that
037: * reason, it implements the <code>Controllable</code> interface
038: * to provide additional controls.
039: *
040: * @see DataSource
041: *
042: */
043:
044: public interface SourceStream extends Controllable {
045:
046: /**
047: * The value returned by <code>getSeekType</code> indicating that this
048: * <code>SourceStream</code> is not seekable.
049: * <p>
050: * Value 0 is assigned to <code>NOT_SEEKABLE</code>.
051: */
052: int NOT_SEEKABLE = 0;
053:
054: /**
055: * The value returned by <code>getSeekType</code> indicating that this
056: * <code>SourceStream</code> can be seeked only to the beginning
057: * of the media stream.
058: * <p>
059: * Value 1 is assigned to <code>SEEKABLE_TO_START</code>.
060: */
061: int SEEKABLE_TO_START = 1;
062:
063: /**
064: * The value returned by <code>getSeekType</code> indicating that this
065: * <code>SourceStream</code> can be seeked anywhere within the media.
066: * <p>
067: * Value 2 is assigned to <code>RANDOM_ACCESSIBLE</code>.
068: */
069: int RANDOM_ACCESSIBLE = 2;
070:
071: /**
072: * Get the content type for this stream.
073: *
074: * @return The current <CODE>ContentDescriptor</CODE> for this stream.
075: */
076: ContentDescriptor getContentDescriptor();
077:
078: /**
079: * Get the size in bytes of the content on this stream.
080: *
081: * @return The content length in bytes. -1 is returned if the
082: * length is not known.
083: */
084: long getContentLength();
085:
086: /**
087: * Reads up to <code>len</code> bytes of data from the input stream into
088: * an array of bytes. An attempt is made to read as many as
089: * <code>len</code> bytes, but a smaller number may be read.
090: * The number of bytes actually read is returned as an integer.
091: *
092: * <p> This method blocks until input data is available, end of file is
093: * detected, or an exception is thrown.
094: *
095: * <p> If <code>b</code> is <code>null</code>, a
096: * <code>NullPointerException</code> is thrown.
097: *
098: * <p> If <code>off</code> is negative, or <code>len</code> is negative, or
099: * <code>off+len</code> is greater than the length of the array
100: * <code>b</code>, then an <code>IndexOutOfBoundsException</code> is
101: * thrown.
102: *
103: * <p> If <code>len</code> is zero, then no bytes are read and
104: * <code>0</code> is returned; otherwise, there is an attempt to read at
105: * least one byte. If no byte is available because the stream is at end of
106: * file, the value <code>-1</code> is returned; otherwise, at least one
107: * byte is read and stored into <code>b</code>.
108: *
109: * <p> The first byte read is stored into element <code>b[off]</code>, the
110: * next one into <code>b[off+1]</code>, and so on. The number of bytes read
111: * is, at most, equal to <code>len</code>. Let <i>k</i> be the number of
112: * bytes actually read; these bytes will be stored in elements
113: * <code>b[off]</code> through <code>b[off+</code><i>k</i><code>-1]</code>,
114: * leaving elements <code>b[off+</code><i>k</i><code>]</code> through
115: * <code>b[off+len-1]</code> unaffected.
116: *
117: * <p> If the first byte cannot be read for any reason other than end of
118: * file, then an <code>IOException</code> is thrown. In particular, an
119: * <code>IOException</code> is thrown if the input stream has been closed.
120: *
121: * @param b the buffer into which the data is read.
122: * @param off the start offset in array <code>b</code>
123: * at which the data is written.
124: * @param len the maximum number of bytes to read.
125: * @return the total number of bytes read into the buffer, or
126: * <code>-1</code> if there is no more data because the end of
127: * the stream has been reached.
128: * @exception IOException if an I/O error occurs.
129: */
130: int read(byte[] b, int off, int len) throws IOException;
131:
132: /**
133: * Get the size of a "logical" chunk of media data from the source.
134: * This method can be used to determine the minimum size of the
135: * buffer to use in conjunction with the <code>read</code> method
136: * to read data from the source.
137: *
138: * @return The minimum size of the buffer needed to read a "logical"
139: * chunk of data from the source. Returns -1 if the size cannot be
140: * determined.
141: * @see #read(byte[], int, int)
142: */
143: int getTransferSize();
144:
145: /**
146: * Seek to the specified point in the stream. The <code>seek</code>
147: * method may, for a variety of reasons, fail to seek to the specified
148: * position. For example,
149: * it may be asked to seek to a position beyond the size of the stream;
150: * or the stream may only be seekable to the beginning
151: * (<code>getSeekType</code> returns <code>SEEKABLE_TO_START</code>).
152: * The return value indicates whether the seeking is successful.
153: * If it is successful, the value returned will be the same as the
154: * given position. Otherwise, the return value will indicate what
155: * the new position is.
156: * <p>
157: * If the given position is negative, seek will treat that as 0
158: * and attempt to seek to 0.
159: * <p>
160: * An IOException will be thrown if an I/O error occurs, e.g. when
161: * the stream comes from a remote connection and the connection is
162: * broken.
163: *
164: * @param where The position to seek to.
165: * @return The new stream position.
166: * @exception IOException Thrown if an I/O error occurs.
167: */
168: long seek(long where) throws IOException;
169:
170: /**
171: * Obtain the current position in the stream.
172: * @return The current position in the stream.
173: */
174: long tell();
175:
176: /**
177: * Find out if the stream is seekable.
178: * The return value can be one of these three:
179: * <code>NOT_SEEKABLE</code>, <code>SEEKABLE_TO_START</code> and
180: * <code>RANDOM_ACCESSIBLE</code>.
181: * If the return value is <code>SEEKABLE_TO_START</code>, it means
182: * that the stream can only be repositioned to the beginning of
183: * the stream. If the return value is <code>RANDOM_ACCESSIBLE</code>,
184: * the stream can be seeked anywhere within the stream.
185: *
186: * @return Returns an enumerated value to indicate the level of seekability.
187: */
188: int getSeekType();
189: }
|