Added in API level 28

MbmsDownloadSession

open class MbmsDownloadSession : AutoCloseable
kotlin.Any
   ↳ android.telephony.MbmsDownloadSession

This class provides functionality for file download over MBMS.

Summary

Constants
static String

The default directory name for all MBMS temp files.
static String

Uri extra that Android will attach to the intent supplied via android.telephony.mbms.DownloadRequest.Builder#setAppIntent(Intent) Indicates the location of the successfully downloaded file within the directory that the app provided via the builder.
static String

Extra containing the DownloadRequest for which the download result or file descriptor request is for.
static String

Integer extra that Android will attach to the intent supplied via android.telephony.mbms.DownloadRequest.Builder#setAppIntent(Intent) Indicates the result code of the download.
static String

FileInfo extra that Android will attach to the intent supplied via android.telephony.mbms.DownloadRequest.Builder#setAppIntent(Intent) Indicates the file for which the download result is for.
static Int

Indicates that the download was cancelled via cancelDownload(android.telephony.mbms.DownloadRequest).
static Int

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.
static Int

Indicates that the download will not be completed due to the expiration of its download window on the carrier's network.
static Int

Indicates that the file root that was set is currently unreachable.
static Int

Indicates that the download will not be completed due to an I/O error incurred while writing to temp files.
static Int

Indicates that the file system is full and the DownloadRequest can not complete.
static Int

Indicates that the Service ID specified in the DownloadRequest is incorrect due to the Id being incorrect, stale, expired, or similar.
static Int

Indicates that the download was successful.
static Int

Indicates that the file is actively being downloaded.
static Int

Indicates that the file is awaiting the next download or repair operations.
static Int

Indicates that the file is waiting to download because its download window has not yet started and is scheduled for a future time.
static Int

Indicates that the file is awaiting file repair after the download has ended.
static Int

Indicates that the middleware has no information on the file.
Public methods
open Unit

Registers a progress listener for a DownloadRequest previously requested via download(android.telephony.mbms.DownloadRequest).
open Unit

Inform the middleware of a service announcement descriptor received from a group communication server.
open Unit

Registers a download status listener for a DownloadRequest previously requested via download(android.telephony.mbms.DownloadRequest).
open Unit
cancelDownload(downloadRequest: DownloadRequest)

Attempts to cancel the specified DownloadRequest.
open Unit

Terminates this instance.
open static MbmsDownloadSession!
create(context: Context, executor: Executor, callback: MbmsDownloadSessionCallback)

Create a new MbmsDownloadSession using the system default data subscription ID.
open static MbmsDownloadSession?
create(context: Context, executor: Executor, subscriptionId: Int, callback: MbmsDownloadSessionCallback)

Create a new MbmsDownloadManager using the given subscription ID.
open Unit

Requests the download of a file or set of files that the carrier has indicated to be available.
open static Int

Returns the maximum size of the service announcement descriptor that can be provided via addServiceAnnouncement
open File?

Retrieves the currently configured temp file root directory.
open MutableList<DownloadRequest!>

Returns a list of pending DownloadRequests that originated from this application.
open Unit

Un-register a listener previously registered via addProgressListener(android.telephony.mbms.DownloadRequest,java.util.concurrent.Executor,android.telephony.mbms.DownloadProgressListener).
open Unit

Un-register a listener previously registered via addStatusListener(android.telephony.mbms.DownloadRequest,java.util.concurrent.Executor,android.telephony.mbms.DownloadStatusListener).
open Unit
requestDownloadState(downloadRequest: DownloadRequest!, fileInfo: FileInfo!)

Requests information about the state of a file pending download.
open Unit

An inspection API to retrieve the list of available android.telephony.mbms.FileServiceInfos currently being advertised.
open Unit

Resets the middleware's knowledge of previously-downloaded files in this download request.
open Unit
setTempFileRootDirectory(tempFileRootDirectory: File)

Sets the temp file root for downloads.

Constants

DEFAULT_TOP_LEVEL_TEMP_DIRECTORY

Added in API level 28
static val DEFAULT_TOP_LEVEL_TEMP_DIRECTORY: String

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().

Value: "androidMbmsTempFileRoot"

EXTRA_MBMS_COMPLETED_FILE_URI

Added in API level 28
static val EXTRA_MBMS_COMPLETED_FILE_URI: String

Uri extra that Android will attach to the intent supplied via android.telephony.mbms.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.

Value: "android.telephony.extra.MBMS_COMPLETED_FILE_URI"

EXTRA_MBMS_DOWNLOAD_REQUEST

Added in API level 28
static val EXTRA_MBMS_DOWNLOAD_REQUEST: String

Extra containing the DownloadRequest for which the download result or file descriptor request is for. Must not be null.

Value: "android.telephony.extra.MBMS_DOWNLOAD_REQUEST"

EXTRA_MBMS_DOWNLOAD_RESULT

Added in API level 28
static val EXTRA_MBMS_DOWNLOAD_RESULT: String

Integer extra that Android will attach to the intent supplied via android.telephony.mbms.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.

Value: "android.telephony.extra.MBMS_DOWNLOAD_RESULT"

EXTRA_MBMS_FILE_INFO

Added in API level 28
static val EXTRA_MBMS_FILE_INFO: String

FileInfo extra that Android will attach to the intent supplied via android.telephony.mbms.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.

Value: "android.telephony.extra.MBMS_FILE_INFO"

RESULT_CANCELLED

Added in API level 28
static val RESULT_CANCELLED: Int

Indicates that the download was cancelled via cancelDownload(android.telephony.mbms.DownloadRequest).

Value: 2

RESULT_DOWNLOAD_FAILURE

Added in API level 28
static val RESULT_DOWNLOAD_FAILURE: Int

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.

Value: 6

RESULT_EXPIRED

Added in API level 28
static val RESULT_EXPIRED: Int

Indicates that the download will not be completed due to the expiration of its download window on the carrier's network.

Value: 3

RESULT_FILE_ROOT_UNREACHABLE

Added in API level 28
static val RESULT_FILE_ROOT_UNREACHABLE: Int

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.

Value: 8

RESULT_IO_ERROR

Added in API level 28
static val RESULT_IO_ERROR: Int

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.

Value: 4

RESULT_OUT_OF_STORAGE

Added in API level 28
static val RESULT_OUT_OF_STORAGE: Int

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.

Value: 7

RESULT_SERVICE_ID_NOT_DEFINED

Added in API level 28
static val RESULT_SERVICE_ID_NOT_DEFINED: Int

Indicates that the Service ID specified in the DownloadRequest is incorrect due to the Id being incorrect, stale, expired, or similar.

Value: 5

RESULT_SUCCESSFUL

Added in API level 28
static val RESULT_SUCCESSFUL: Int

Indicates that the download was successful.

Value: 1

STATUS_ACTIVELY_DOWNLOADING

Added in API level 28
static val STATUS_ACTIVELY_DOWNLOADING: Int

Indicates that the file is actively being downloaded.

Value: 1

STATUS_PENDING_DOWNLOAD

Added in API level 28
static val STATUS_PENDING_DOWNLOAD: Int

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.

Value: 2

STATUS_PENDING_DOWNLOAD_WINDOW

Added in API level 28
static val STATUS_PENDING_DOWNLOAD_WINDOW: Int

Indicates that the file is waiting to download because its download window has not yet started and is scheduled for a future time.

Value: 4

STATUS_PENDING_REPAIR

Added in API level 28
static val STATUS_PENDING_REPAIR: Int

Indicates that the file is awaiting file repair after the download has ended.

Value: 3

STATUS_UNKNOWN

Added in API level 28
static val STATUS_UNKNOWN: Int

Indicates that the middleware has no information on the file.

Value: 0

Public methods

addProgressListener

Added in API level 28
open fun addProgressListener(
    request: DownloadRequest, 
    executor: Executor, 
    listener: DownloadProgressListener
): Unit

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

Added in API level 31
open fun addServiceAnnouncement(contents: ByteArray): Unit

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 ByteArray: 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

Added in API level 28
open fun addStatusListener(
    request: DownloadRequest, 
    executor: Executor, 
    listener: DownloadStatusListener
): Unit

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

Added in API level 28
open fun cancelDownload(downloadRequest: DownloadRequest): Unit

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

Added in API level 28
open fun close(): Unit

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

Exceptions
java.lang.Exception if this resource cannot be closed

create

Added in API level 28
open static fun create(
    context: Context, 
    executor: Executor, 
    callback: MbmsDownloadSessionCallback
): MbmsDownloadSession!

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.

create

Added in API level 28
open static fun create(
    context: Context, 
    executor: Executor, 
    subscriptionId: Int, 
    callback: MbmsDownloadSessionCallback
): MbmsDownloadSession?

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.
Return
MbmsDownloadSession? A new instance of MbmsDownloadSession, or null if an error occurred during setup.

download

Added in API level 28
open fun download(request: DownloadRequest): Unit

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

Added in API level 31
open static fun getMaximumServiceAnnouncementSize(): Int

Returns the maximum size of the service announcement descriptor that can be provided via addServiceAnnouncement

Return
Int The maximum length of the byte array passed as an argument to addServiceAnnouncement.

getTempFileRootDirectory

Added in API level 28
open fun getTempFileRootDirectory(): File?

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.

Return
File? A File pointing to the configured temp file directory, or null if not yet configured.

listPendingDownloads

Added in API level 28
open fun listPendingDownloads(): MutableList<DownloadRequest!>

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).

Return
MutableList<DownloadRequest!> A list, possibly empty, of DownloadRequests This value cannot be null.

removeProgressListener

Added in API level 28
open fun removeProgressListener(
    request: DownloadRequest, 
    listener: DownloadProgressListener
): Unit

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

Added in API level 28
open fun removeStatusListener(
    request: DownloadRequest, 
    listener: DownloadStatusListener
): Unit

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

Added in API level 28
open fun requestDownloadState(
    downloadRequest: DownloadRequest!, 
    fileInfo: FileInfo!
): Unit

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

Added in API level 28
open fun requestUpdateFileServices(classList: MutableList<String!>): Unit

An inspection API to retrieve the list of available android.telephony.mbms.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 MutableList<String!>: 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

Added in API level 28
open fun resetDownloadKnowledge(downloadRequest: DownloadRequest!): Unit

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

Added in API level 28
open fun setTempFileRootDirectory(tempFileRootDirectory: File): Unit

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 android.content.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.