loliball/media
1
0
Fork 0
mirror of https://github.com/androidx/media.git synced 2025-05-07 23:50:44 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Document DataSource edge-case behaviors

Browse Source 
PiperOrigin-RevId: 362386100
This commit is contained in:
olly 2021-03-11 23:05:53 +00:00 committed by Ian Baker
parent 4665ac5490
commit 1a68f3d3a4
1 changed files with 22 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
library/common/src/main/java/com/google/android/exoplayer2/upstream/DataSource.java
View File

@ -45,17 +45,31 @@ public interface DataSource extends DataReader {
void addTransferListener(TransferListener transferListener); void addTransferListener(TransferListener transferListener);
/** /**
* Opens the source to read the specified data. * Opens the source to read the specified data. If an {@link IOException} is thrown, callers must
* <p> * still call {@link #close()} to ensure that any partial effects of the invocation are cleaned
* Note: If an {@link IOException} is thrown, callers must still call {@link #close()} to ensure * up.
* that any partial effects of the invocation are cleaned up. *
* <p>The following edge case behaviors apply:
*
* <ul>
* <li>If the {@link DataSpec#position requested position} is within the resource, but the
* {@link DataSpec#length requested length} extends beyond the end of the resource, then
* {@link #open} will succeed and data from the requested position to the end of the
* resource will be made available through {@link #read}.
* <li>If the {@link DataSpec#position requested position} is equal to the length of the
* resource, then {@link #open} will succeed, and {@link #read} will immediately return
* {@link C#RESULT_END_OF_INPUT}.
* <li>If the {@link DataSpec#position requested position} is greater than the length of the
* resource, then {@link #open} will throw an {@link IOException} for which {@link
* DataSourceException#isCausedByPositionOutOfRange} will be {@code true}.
* </ul>
* *
* @param dataSpec Defines the data to be read. * @param dataSpec Defines the data to be read.
* @throws IOException If an error occurs opening the source. {@link DataSourceException} can be * @throws IOException If an error occurs opening the source. {@link DataSourceException} can be
* thrown or used as a cause of the thrown exception to specify the reason of the error. * thrown or used as a cause of the thrown exception to specify the reason of the error.
* @return The number of bytes that can be read from the opened source. For unbounded requests * @return The number of bytes that can be read from the opened source. For unbounded requests
* (i.e. requests where {@link DataSpec#length} equals {@link C#LENGTH_UNSET}) this value * (i.e., requests where {@link DataSpec#length} equals {@link C#LENGTH_UNSET}) this value is
* is the resolved length of the request, or {@link C#LENGTH_UNSET} if the length is still * the resolved length of the request, or {@link C#LENGTH_UNSET} if the length is still
* unresolved. For all other requests, the value returned will be equal to the request's * unresolved. For all other requests, the value returned will be equal to the request's
* {@link DataSpec#length}. * {@link DataSpec#length}.
*/ */
@ -82,10 +96,8 @@ public interface DataSource extends DataReader {
} }
/** /**
* Closes the source. * Closes the source. This method must be called even if the corresponding call to {@link
* <p> * #open(DataSpec)} threw an {@link IOException}.
* Note: This method must be called even if the corresponding call to {@link #open(DataSpec)}
* threw an {@link IOException}. See {@link #open(DataSpec)} for more details.
* *
* @throws IOException If an error occurs closing the source. * @throws IOException If an error occurs closing the source.
*/ */