MbmsDownloadSession
public
class
MbmsDownloadSession
extends Object
implements
AutoCloseable
| java.lang.Object | |
| ↳ | android.telephony.MbmsDownloadSession |
This class provides functionality for file download over MBMS.
Summary
Constants | |
|---|---|
String |
DEFAULT_TOP_LEVEL_TEMP_DIRECTORY
The default directory name for all MBMS temp files. |
String |
EXTRA_MBMS_COMPLETED_FILE_URI
|
String |
EXTRA_MBMS_DOWNLOAD_REQUEST
Extra containing the |
String |
EXTRA_MBMS_DOWNLOAD_RESULT
Integer extra that Android will attach to the intent supplied via
|
String |
EXTRA_MBMS_FILE_INFO
|
int |
RESULT_CANCELLED
Indicates that the download was cancelled via |
int |
RESULT_DOWNLOAD_FAILURE
Indicates that there was an error while processing downloaded files, such as a file repair or file decoding error and is not due to a file I/O error. |
int |
RESULT_EXPIRED
Indicates that the download will not be completed due to the expiration of its download window on the carrier's network. |
int |
RESULT_FILE_ROOT_UNREACHABLE
Indicates that the file root that was set is currently unreachable. |
int |
RESULT_IO_ERROR
Indicates that the download will not be completed due to an I/O error incurred while writing to temp files. |
int |
RESULT_OUT_OF_STORAGE
Indicates that the file system is full and the |
int |
RESULT_SERVICE_ID_NOT_DEFINED
Indicates that the Service ID specified in the |
int |
RESULT_SUCCESSFUL
Indicates that the download was successful. |
int |
STATUS_ACTIVELY_DOWNLOADING
Indicates that the file is actively being downloaded. |
int |
STATUS_PENDING_DOWNLOAD
Indicates that the file is awaiting the next download or repair operations. |
int |
STATUS_PENDING_DOWNLOAD_WINDOW
Indicates that the file is waiting to download because its download window has not yet started and is scheduled for a future time. |
int |
STATUS_PENDING_REPAIR
Indicates that the file is awaiting file repair after the download has ended. |
int |
STATUS_UNKNOWN
Indicates that the middleware has no information on the file. |
Public methods | |
|---|---|
void
|
addProgressListener(DownloadRequest request, Executor executor, DownloadProgressListener listener)
Registers a progress listener for a |
void
|
addServiceAnnouncement(byte[] contents)
Inform the middleware of a service announcement descriptor received from a group communication server. |
void
|
addStatusListener(DownloadRequest request, Executor executor, DownloadStatusListener listener)
Registers a download status listener for a |
void
|
cancelDownload(DownloadRequest downloadRequest)
Attempts to cancel the specified |
void
|
close()
Terminates this instance. |
static
MbmsDownloadSession
|
create(Context context, Executor executor, int subscriptionId, MbmsDownloadSessionCallback callback)
Create a new MbmsDownloadManager using the given subscription ID. |
static
MbmsDownloadSession
|
create(Context context, Executor executor, MbmsDownloadSessionCallback callback)
Create a new |
void
|
download(DownloadRequest request)
Requests the download of a file or set of files that the carrier has indicated to be available. |
static
int
|
getMaximumServiceAnnouncementSize()
Returns the maximum size of the service announcement descriptor that can be provided via
|
File
|
getTempFileRootDirectory()
Retrieves the currently configured temp file root directory. |
List<DownloadRequest>
|
listPendingDownloads()
Returns a list of pending |
void
|
removeProgressListener(DownloadRequest request, DownloadProgressListener listener)
Un-register a listener previously registered via
|
void
|
removeStatusListener(DownloadRequest request, DownloadStatusListener listener)
Un-register a listener previously registered via
|
void
|
requestDownloadState(DownloadRequest downloadRequest, FileInfo fileInfo)
Requests information about the state of a file pending download. |
void
|
requestUpdateFileServices(List<String> classList)
An inspection API to retrieve the list of available
|
void
|
resetDownloadKnowledge(DownloadRequest downloadRequest)
Resets the middleware's knowledge of previously-downloaded files in this download request. |
void
|
setTempFileRootDirectory(File tempFileRootDirectory)
Sets the temp file root for downloads. |
Inherited methods | |
|---|---|
Constants
DEFAULT_TOP_LEVEL_TEMP_DIRECTORY
public static final String DEFAULT_TOP_LEVEL_TEMP_DIRECTORY
The default directory name for all MBMS temp files. If you call
download(android.telephony.mbms.DownloadRequest) without first calling
setTempFileRootDirectory(java.io.File), this directory will be created for you under the
path returned by Context#getFilesDir().
Constant Value: "androidMbmsTempFileRoot"
EXTRA_MBMS_COMPLETED_FILE_URI
public static final String EXTRA_MBMS_COMPLETED_FILE_URI
Uri extra that Android will attach to the intent supplied via
DownloadRequest.Builder.setAppIntent(Intent)
Indicates the location of the successfully downloaded file within the directory that the
app provided via the builder.
Will always be set to a non-null value if
EXTRA_MBMS_DOWNLOAD_RESULT is set to RESULT_SUCCESSFUL.
Constant Value: "android.telephony.extra.MBMS_COMPLETED_FILE_URI"
EXTRA_MBMS_DOWNLOAD_REQUEST
public static final String EXTRA_MBMS_DOWNLOAD_REQUEST
Extra containing the DownloadRequest for which the download result or file
descriptor request is for. Must not be null.
Constant Value: "android.telephony.extra.MBMS_DOWNLOAD_REQUEST"
EXTRA_MBMS_DOWNLOAD_RESULT
public static final String EXTRA_MBMS_DOWNLOAD_RESULT
Integer extra that Android will attach to the intent supplied via
DownloadRequest.Builder.setAppIntent(Intent)
Indicates the result code of the download. One of
RESULT_SUCCESSFUL, RESULT_EXPIRED, RESULT_CANCELLED,
RESULT_IO_ERROR, RESULT_DOWNLOAD_FAILURE, RESULT_OUT_OF_STORAGE,
RESULT_SERVICE_ID_NOT_DEFINED, or RESULT_FILE_ROOT_UNREACHABLE.
This extra may also be used by the middleware when it is sending intents to the app.
Constant Value: "android.telephony.extra.MBMS_DOWNLOAD_RESULT"
EXTRA_MBMS_FILE_INFO
public static final String EXTRA_MBMS_FILE_INFO
FileInfo extra that Android will attach to the intent supplied via
DownloadRequest.Builder.setAppIntent(Intent)
Indicates the file for which the download result is for. Never null.
This extra may also be used by the middleware when it is sending intents to the app.
Constant Value: "android.telephony.extra.MBMS_FILE_INFO"
RESULT_CANCELLED
public static final int RESULT_CANCELLED
Indicates that the download was cancelled via cancelDownload(android.telephony.mbms.DownloadRequest).
Constant Value: 2 (0x00000002)
RESULT_DOWNLOAD_FAILURE
public static final int RESULT_DOWNLOAD_FAILURE
Indicates that there was an error while processing downloaded files, such as a file repair or
file decoding error and is not due to a file I/O error.
This is likely a transient error and another DownloadRequest should be sent to try
the download again.
Constant Value: 6 (0x00000006)
RESULT_EXPIRED
public static final int RESULT_EXPIRED
Indicates that the download will not be completed due to the expiration of its download window on the carrier's network.
Constant Value: 3 (0x00000003)
RESULT_FILE_ROOT_UNREACHABLE
public static final int RESULT_FILE_ROOT_UNREACHABLE
Indicates that the file root that was set is currently unreachable. This can happen if the temp files are set to be stored on external storage and the SD card was removed, for example. The temp file root should be changed before sending another DownloadRequest.
Constant Value: 8 (0x00000008)
RESULT_IO_ERROR
public static final int RESULT_IO_ERROR
Indicates that the download will not be completed due to an I/O error incurred while
writing to temp files.
This is likely a transient error and another DownloadRequest should be sent to try
the download again.
Constant Value: 4 (0x00000004)
RESULT_OUT_OF_STORAGE
public static final int RESULT_OUT_OF_STORAGE
Indicates that the file system is full and the DownloadRequest can not complete.
Either space must be made on the current file system or the temp file root location must be
changed to a location that is not full to download the temp files.
Constant Value: 7 (0x00000007)
RESULT_SERVICE_ID_NOT_DEFINED
public static final int RESULT_SERVICE_ID_NOT_DEFINED
Indicates that the Service ID specified in the DownloadRequest is incorrect due to
the Id being incorrect, stale, expired, or similar.
Constant Value: 5 (0x00000005)
RESULT_SUCCESSFUL
public static final int RESULT_SUCCESSFUL
Indicates that the download was successful.
Constant Value: 1 (0x00000001)
STATUS_ACTIVELY_DOWNLOADING
public static final int STATUS_ACTIVELY_DOWNLOADING
Indicates that the file is actively being downloaded.
Constant Value: 1 (0x00000001)
STATUS_PENDING_DOWNLOAD
public static final int STATUS_PENDING_DOWNLOAD
Indicates that the file is awaiting the next download or repair operations. When a more
precise status is known, the status will change to either STATUS_PENDING_REPAIR or
STATUS_PENDING_DOWNLOAD_WINDOW.
Constant Value: 2 (0x00000002)
STATUS_PENDING_DOWNLOAD_WINDOW
public static final int STATUS_PENDING_DOWNLOAD_WINDOW
Indicates that the file is waiting to download because its download window has not yet started and is scheduled for a future time.
Constant Value: 4 (0x00000004)
STATUS_PENDING_REPAIR
public static final int STATUS_PENDING_REPAIR
Indicates that the file is awaiting file repair after the download has ended.
Constant Value: 3 (0x00000003)
STATUS_UNKNOWN
public static final int STATUS_UNKNOWN
Indicates that the middleware has no information on the file.
Constant Value: 0 (0x00000000)
Public methods
addProgressListener
public void addProgressListener (DownloadRequest request, Executor executor, DownloadProgressListener listener)
Registers a progress listener for a DownloadRequest previously requested via
download(android.telephony.mbms.DownloadRequest). This listener will only be called as long as both this
app and the middleware are both running -- if either one stops, no further calls on the
provided DownloadProgressListener will be enqueued.
If the middleware is not aware of the specified download request,
this method will throw an IllegalArgumentException.
If the operation encountered an error, the error code will be delivered via
MbmsDownloadSessionCallback#onError.
Repeated calls to this method for the same DownloadRequest will replace the
previously registered listener.
| Parameters | |
|---|---|
request |
DownloadRequest: The DownloadRequest that you want updates on.
This value cannot be null. |
executor |
Executor: The Executor on which calls to listener should be executed.
This value cannot be null. |
listener |
DownloadProgressListener: The listener that should be called when the middleware has information to
share on the progress of the download.
This value cannot be null. |
addServiceAnnouncement
public void addServiceAnnouncement (byte[] contents)
Inform the middleware of a service announcement descriptor received from a group
communication server.
When participating in a group call via the MbmsGroupCallSession API, applications may
receive a service announcement descriptor from the group call server that informs them of
files that may be relevant to users communicating on the group call.
After supplying the service announcement descriptor received from the server to the
middleware via this API, applications will receive information on the available files via
MbmsDownloadSessionCallback#onFileServicesUpdated, and the available files will be
downloadable via MbmsDownloadSession#download like other files published via
MbmsDownloadSessionCallback#onFileServicesUpdated.
Asynchronous error codes via the MbmsDownloadSessionCallback#onError(int, String)
callback may include any of the errors that are not specific to the streaming use-case.
May throw an IllegalStateException when the middleware has not yet been bound,
or an IllegalArgumentException if the byte array is too large, or an
UnsupportedOperationException if the middleware has not implemented this method.
| Parameters | |
|---|---|
contents |
byte: The contents of the service announcement descriptor received from the
group call server. If the size of this array is greater than the value of
getMaximumServiceAnnouncementSize(), an
IllegalArgumentException will be thrown.
This value cannot be null. |
addStatusListener
public void addStatusListener (DownloadRequest request, Executor executor, DownloadStatusListener listener)
Registers a download status listener for a DownloadRequest previously requested via
download(android.telephony.mbms.DownloadRequest). This callback will only be called as long as both this
app and the middleware are both running -- if either one stops, no further calls on the
provided DownloadStatusListener will be enqueued.
If the middleware is not aware of the specified download request,
this method will throw an IllegalArgumentException.
If the operation encountered an error, the error code will be delivered via
MbmsDownloadSessionCallback#onError.
Repeated calls to this method for the same DownloadRequest will replace the
previously registered listener.
| Parameters | |
|---|---|
request |
DownloadRequest: The DownloadRequest that you want updates on.
This value cannot be null. |
executor |
Executor: The Executor on which calls to listener should be executed.
This value cannot be null. |
listener |
DownloadStatusListener: The listener that should be called when the middleware has information to
share on the status download.
This value cannot be null. |
cancelDownload
public void cancelDownload (DownloadRequest downloadRequest)
Attempts to cancel the specified DownloadRequest.
If the operation encountered an error, the error code will be delivered via
MbmsDownloadSessionCallback#onError.
| Parameters | |
|---|---|
downloadRequest |
DownloadRequest: The download request that you wish to cancel.
This value cannot be null. |
close
public void close ()
Terminates this instance.
After this method returns,
no further callbacks originating from the middleware will be enqueued on the provided
instance of MbmsDownloadSessionCallback, but callbacks that have already been
enqueued will still be delivered.
It is safe to call create(android.content.Context, java.util.concurrent.Executor, int, android.telephony.mbms.MbmsDownloadSessionCallback) to
obtain another instance of MbmsDownloadSession immediately after this method
returns.
May throw an IllegalStateException
create
public static MbmsDownloadSession create (Context context, Executor executor, int subscriptionId, MbmsDownloadSessionCallback callback)
Create a new MbmsDownloadManager using the given subscription ID.
Note that this call will bind a remote service and that may take a bit. The instance of
MbmsDownloadSession that is returned will not be ready for use until
MbmsDownloadSessionCallback#onMiddlewareReady() is called on the provided callback.
If you attempt to use the instance before it is ready, an IllegalStateException
will be thrown or an error will be delivered through
MbmsDownloadSessionCallback#onError(int, String).
This also may throw an IllegalArgumentException.
You may only have one instance of MbmsDownloadSession per UID. If you call this
method while there is an active instance of MbmsDownloadSession in your process
(in other words, one that has not had close() called on it), this method will
throw an IllegalStateException. If you call this method in a different process
running under the same UID, an error will be indicated via
MbmsDownloadSessionCallback#onError(int, String).
Note that initialization may fail asynchronously. If you wish to try again after you
receive such an asynchronous error, you must call close() on the instance of
MbmsDownloadSession that you received before calling this method again.
| Parameters | |
|---|---|
context |
Context: The instance of Context to use
This value cannot be null. |
executor |
Executor: The executor on which you wish to execute callbacks.
This value cannot be null. |
subscriptionId |
int: The data subscription ID to use |
callback |
MbmsDownloadSessionCallback: A callback to get asynchronous error messages and file service updates.
This value cannot be null. |
| Returns | |
|---|---|
MbmsDownloadSession |
A new instance of MbmsDownloadSession, or null if an error occurred during
setup. |
create
public static MbmsDownloadSession create (Context context, Executor executor, MbmsDownloadSessionCallback callback)
Create a new MbmsDownloadSession using the system default data subscription ID.
See create(android.content.Context, java.util.concurrent.Executor, int, android.telephony.mbms.MbmsDownloadSessionCallback)
| Parameters | |
|---|---|
context |
Context: This value cannot be null. |
executor |
Executor: This value cannot be null. |
callback |
MbmsDownloadSessionCallback: This value cannot be null. |
| Returns | |
|---|---|
MbmsDownloadSession |
|
download
public void download (DownloadRequest request)
Requests the download of a file or set of files that the carrier has indicated to be
available.
May throw an IllegalArgumentException
If setTempFileRootDirectory(java.io.File) has not called after the app has been installed,
this method will create a directory at the default location defined at
MbmsDownloadSession#DEFAULT_TOP_LEVEL_TEMP_DIRECTORY and store that as the temp
file root directory.
If the DownloadRequest has a destination that is not on the same filesystem as the
temp file directory provided via getTempFileRootDirectory(), an
IllegalArgumentException will be thrown.
Asynchronous errors through the callback may include any error not specific to the
streaming use-case.
If no error is delivered via the callback after calling this method, that means that the
middleware has successfully started the download or scheduled the download, if the download
is at a future time.
| Parameters | |
|---|---|
request |
DownloadRequest: The request that specifies what should be downloaded.
This value cannot be null. |
getMaximumServiceAnnouncementSize
public static int getMaximumServiceAnnouncementSize ()
Returns the maximum size of the service announcement descriptor that can be provided via
addServiceAnnouncement(byte)
| Returns | |
|---|---|
int |
The maximum length of the byte array passed as an argument to
addServiceAnnouncement(byte). |
getTempFileRootDirectory
public File getTempFileRootDirectory ()
Retrieves the currently configured temp file root directory. Returns the file that was
configured via setTempFileRootDirectory(java.io.File) or the default directory
download(android.telephony.mbms.DownloadRequest) was called without ever
setting the temp file root. If neither method has been called since the last time the app's
shared preferences were reset, returns null.
| Returns | |
|---|---|
File |
A File pointing to the configured temp file directory, or null if not yet
configured. |
listPendingDownloads
public List<DownloadRequest> listPendingDownloads ()
Returns a list of pending DownloadRequests that originated from this application.
A pending request is one that was issued via
download(android.telephony.mbms.DownloadRequest) but not cancelled through
cancelDownload(android.telephony.mbms.DownloadRequest).
| Returns | |
|---|---|
List<DownloadRequest> |
A list, possibly empty, of DownloadRequests
This value cannot be null. |
removeProgressListener
public void removeProgressListener (DownloadRequest request, DownloadProgressListener listener)
Un-register a listener previously registered via
addProgressListener(android.telephony.mbms.DownloadRequest, java.util.concurrent.Executor, android.telephony.mbms.DownloadProgressListener). After
this method is called, no further callbacks will be enqueued on the Handler
provided upon registration, even if this method throws an exception.
If the middleware is not aware of the specified download request,
this method will throw an IllegalArgumentException.
If the operation encountered an error, the error code will be delivered via
MbmsDownloadSessionCallback#onError.
| Parameters | |
|---|---|
request |
DownloadRequest: The DownloadRequest provided during registration
This value cannot be null. |
listener |
DownloadProgressListener: The listener provided during registration.
This value cannot be null. |
removeStatusListener
public void removeStatusListener (DownloadRequest request, DownloadStatusListener listener)
Un-register a listener previously registered via
addStatusListener(android.telephony.mbms.DownloadRequest, java.util.concurrent.Executor, android.telephony.mbms.DownloadStatusListener). After
this method is called, no further calls will be enqueued on the Executor
provided upon registration, even if this method throws an exception.
If the middleware is not aware of the specified download request,
this method will throw an IllegalArgumentException.
If the operation encountered an error, the error code will be delivered via
MbmsDownloadSessionCallback#onError.
| Parameters | |
|---|---|
request |
DownloadRequest: The DownloadRequest provided during registration
This value cannot be null. |
listener |
DownloadStatusListener: The listener provided during registration.
This value cannot be null. |
requestDownloadState
public void requestDownloadState (DownloadRequest downloadRequest, FileInfo fileInfo)
Requests information about the state of a file pending download.
The state will be delivered as a callback via
DownloadStatusListener#onStatusUpdated(DownloadRequest, FileInfo, int). If no such
callback has been registered via
addProgressListener(android.telephony.mbms.DownloadRequest, java.util.concurrent.Executor, android.telephony.mbms.DownloadProgressListener), this
method will be a no-op.
If the middleware has no record of the
file indicated by fileInfo being associated with downloadRequest,
an IllegalArgumentException will be thrown.
| Parameters | |
|---|---|
downloadRequest |
DownloadRequest: The download request to query. |
fileInfo |
FileInfo: The particular file within the request to get information on. |
requestUpdateFileServices
public void requestUpdateFileServices (List<String> classList)
An inspection API to retrieve the list of available
FileServiceInfos currently being advertised.
The results are returned asynchronously via a call to
MbmsDownloadSessionCallback#onFileServicesUpdated(List)
Asynchronous error codes via the MbmsDownloadSessionCallback#onError(int, String)
callback may include any of the errors that are not specific to the streaming use-case.
May throw an IllegalStateException or IllegalArgumentException.
| Parameters | |
|---|---|
classList |
List: A list of service classes which the app wishes to receive
MbmsDownloadSessionCallback#onFileServicesUpdated(List) callbacks
about. Subsequent calls to this method will replace this list of service
classes (i.e. the middleware will no longer send updates for services
matching classes only in the old list).
Values in this list should be negotiated with the wireless carrier prior
to using this API.
This value cannot be null. |
resetDownloadKnowledge
public void resetDownloadKnowledge (DownloadRequest downloadRequest)
Resets the middleware's knowledge of previously-downloaded files in this download request.
Normally, the middleware keeps track of the hashes of downloaded files and won't re-download
files whose server-reported hash matches one of the already-downloaded files. This means
that if the file is accidentally deleted by the user or by the app, the middleware will
not try to download it again.
This method will reset the middleware's cache of hashes for the provided
DownloadRequest, so that previously downloaded content will be downloaded again
when available.
This will not interrupt in-progress downloads.
This is distinct from cancelling and re-issuing the download request -- if you cancel and
re-issue, the middleware will not clear its cache of download state information.
If the middleware is not aware of the specified download request, an
IllegalArgumentException will be thrown.
| Parameters | |
|---|---|
downloadRequest |
DownloadRequest: The request to re-download files for. |
setTempFileRootDirectory
public void setTempFileRootDirectory (File tempFileRootDirectory)
Sets the temp file root for downloads.
All temp files created for the middleware to write to will be contained in the specified
directory. Applications that wish to specify a location only need to call this method once
as long their data is persisted in storage -- the argument will be stored both in a
local instance of SharedPreferences and by the middleware.
If this method is not called at least once before calling
download(android.telephony.mbms.DownloadRequest), the framework
will default to a directory formed by the concatenation of the app's files directory and
MbmsDownloadSession#DEFAULT_TOP_LEVEL_TEMP_DIRECTORY.
Before calling this method, the app must cancel all of its pending
DownloadRequests via cancelDownload(android.telephony.mbms.DownloadRequest). If this is not done,
you will receive an asynchronous error with code
MbmsErrors.DownloadErrors#ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT unless the
provided directory is the same as what has been previously configured.
The File supplied as a root temp file directory must already exist. If not, an
IllegalArgumentException will be thrown. In addition, as an additional correctness
check, an IllegalArgumentException will be thrown if you attempt to set the temp
file root directory to one of your data roots (the value of Context#getDataDir(),
Context#getFilesDir(), or Context#getCacheDir()).
| Parameters | |
|---|---|
tempFileRootDirectory |
File: A directory to place temp files in.
This value cannot be null. |