JobParameters
open class JobParameters : Parcelable
kotlin.Any | |
↳ | android.app.job.JobParameters |
Contains the parameters used to configure/identify your job. You do not create this object yourself, instead it is handed in to your application by the System.
Summary
Constants | |
---|---|
static Int |
The current standby bucket requires that the job stop now. |
static Int |
The app is restricted from running in the background. |
static Int |
The job was cancelled directly by the app, either by calling |
static Int |
The requested battery-not-low constraint is no longer satisfied. |
static Int |
The requested charging constraint is no longer satisfied. |
static Int |
The requested connectivity constraint is no longer satisfied. |
static Int |
The requested idle constraint is no longer satisfied. |
static Int |
The requested storage-not-low constraint is no longer satisfied. |
static Int |
The device state (eg. Doze, battery saver, memory usage, etc) requires JobScheduler stop this job. |
static Int |
The system's estimate of when the app will be launched changed significantly enough to decide this job shouldn't be running right now. |
static Int |
The job was stopped to run a higher priority job of the app. |
static Int |
The app has consumed all of its current quota. |
static Int |
The system is doing some processing that requires stopping this job. |
static Int |
The job used up its maximum execution time and timed out. |
static Int |
There is no reason the job is stopped. |
static Int |
The user stopped the job. |
Inherited constants | |
---|---|
Public methods | |
---|---|
open Unit |
completeWork(work: JobWorkItem) Report the completion of executing a |
open JobWorkItem? |
Dequeue the next pending |
open Int | |
open ClipData? | |
open Int | |
open PersistableBundle | |
open Int |
getJobId() |
open String? |
Get the namespace this job was placed in. |
open Network? |
Return the network that should be used to perform any network requests for this job. |
open Int | |
open Bundle | |
open Array<String!>? |
For jobs with |
open Array<Uri!>? |
For jobs with |
open Boolean | |
open Boolean |
For jobs with |
open Boolean | |
open Unit |
writeToParcel(dest: Parcel, flags: Int) |
Properties | |
---|---|
static Parcelable.Creator<JobParameters!> |
Constants
STOP_REASON_APP_STANDBY
static val STOP_REASON_APP_STANDBY: Int
The current standby bucket requires that the job stop now.
Value: 12
STOP_REASON_BACKGROUND_RESTRICTION
static val STOP_REASON_BACKGROUND_RESTRICTION: Int
The app is restricted from running in the background.
Value: 11
STOP_REASON_CANCELLED_BY_APP
static val STOP_REASON_CANCELLED_BY_APP: Int
The job was cancelled directly by the app, either by calling JobScheduler#cancel(int)
, JobScheduler#cancelAll()
, or by scheduling a new job with the same job ID.
Value: 1
STOP_REASON_CONSTRAINT_BATTERY_NOT_LOW
static val STOP_REASON_CONSTRAINT_BATTERY_NOT_LOW: Int
The requested battery-not-low constraint is no longer satisfied.
Value: 5
STOP_REASON_CONSTRAINT_CHARGING
static val STOP_REASON_CONSTRAINT_CHARGING: Int
The requested charging constraint is no longer satisfied.
Value: 6
STOP_REASON_CONSTRAINT_CONNECTIVITY
static val STOP_REASON_CONSTRAINT_CONNECTIVITY: Int
The requested connectivity constraint is no longer satisfied.
Value: 7
STOP_REASON_CONSTRAINT_DEVICE_IDLE
static val STOP_REASON_CONSTRAINT_DEVICE_IDLE: Int
The requested idle constraint is no longer satisfied.
Value: 8
STOP_REASON_CONSTRAINT_STORAGE_NOT_LOW
static val STOP_REASON_CONSTRAINT_STORAGE_NOT_LOW: Int
The requested storage-not-low constraint is no longer satisfied.
Value: 9
STOP_REASON_DEVICE_STATE
static val STOP_REASON_DEVICE_STATE: Int
The device state (eg. Doze, battery saver, memory usage, etc) requires JobScheduler stop this job.
Value: 4
STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED
static val STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED: Int
The system's estimate of when the app will be launched changed significantly enough to decide this job shouldn't be running right now. This will mostly apply to prefetch jobs.
Value: 15
STOP_REASON_PREEMPT
static val STOP_REASON_PREEMPT: Int
The job was stopped to run a higher priority job of the app.
Value: 2
STOP_REASON_QUOTA
static val STOP_REASON_QUOTA: Int
The app has consumed all of its current quota. Each app is assigned a quota of how much it can run jobs within a certain time frame. The quota is informed, in part, by app standby buckets. Once an app has used up all of its quota, it won't be able to start jobs until quota is replenished, is changed, or is temporarily not applied.
Value: 10
STOP_REASON_SYSTEM_PROCESSING
static val STOP_REASON_SYSTEM_PROCESSING: Int
The system is doing some processing that requires stopping this job.
Value: 14
STOP_REASON_TIMEOUT
static val STOP_REASON_TIMEOUT: Int
The job used up its maximum execution time and timed out. Each individual job has a maximum execution time limit, regardless of how much total quota the app has. See the note on JobScheduler
and JobInfo
for the execution time limits.
Value: 3
STOP_REASON_UNDEFINED
static val STOP_REASON_UNDEFINED: Int
There is no reason the job is stopped. This is the value returned from the JobParameters object passed to JobService#onStartJob(JobParameters)
.
Value: 0
STOP_REASON_USER
static val STOP_REASON_USER: Int
The user stopped the job. This can happen either through force-stop, adb shell commands, uninstalling, or some other UI.
Value: 13
Public methods
completeWork
open fun completeWork(work: JobWorkItem): Unit
Report the completion of executing a JobWorkItem
previously returned by dequeueWork()
. This tells the system you are done with the work associated with that item, so it will not be returned again. Note that if this is the last work in the queue, completing it here will not finish the overall job -- for that to happen, you still need to call dequeueWork()
again.
If you are enqueueing work into a job, you must call this method for each piece of work you process. Do not call JobService#jobFinished(JobParameters, boolean)
or else you can lose work in your queue.
Parameters | |
---|---|
work |
JobWorkItem: The work you have completed processing, as previously returned by dequeueWork() This value cannot be null . |
dequeueWork
open fun dequeueWork(): JobWorkItem?
Dequeue the next pending JobWorkItem
from these JobParameters associated with their currently running job. Calling this method when there is no more work available and all previously dequeued work has been completed will result in the system taking care of stopping the job for you -- you should not call JobService#jobFinished(JobParameters, boolean)
yourself (otherwise you risk losing an upcoming JobWorkItem that is being enqueued at the same time).
Once you are done with the JobWorkItem
returned by this method, you must call completeWork(android.app.job.JobWorkItem)
with it to inform the system that you are done executing the work. The job will not be finished until all dequeued work has been completed. You do not, however, have to complete each returned work item before deqeueing the next one -- you can use dequeueWork()
multiple times before completing previous work if you want to process work in parallel, and you can complete the work in whatever order you want.
If the job runs to the end of its available time period before all work has been completed, it will stop as normal. You should return true from JobService#onStopJob(JobParameters)
in order to have the job rescheduled, and by doing so any pending as well as remaining uncompleted work will be re-queued for the next time the job runs.
This example shows how to construct a JobService that will serially dequeue and process work that is available for it:
Return | |
---|---|
JobWorkItem? |
Returns a new JobWorkItem if there is one pending, otherwise null. If null is returned, the system will also stop the job if all work has also been completed. (This means that for correct operation, you must always call dequeueWork() after you have completed other work, to check either for more work or allow the system to stop the job.) |
describeContents
open fun describeContents(): Int
Return | |
---|---|
Int |
a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR |
getClipData
open fun getClipData(): ClipData?
Return | |
---|---|
ClipData? |
The clip you passed in when constructing this job with android.app.job.JobInfo.Builder#setClipData(ClipData, int) . Will be null if it was not set. |
getClipGrantFlags
open fun getClipGrantFlags(): Int
Return | |
---|---|
Int |
The clip grant flags you passed in when constructing this job with android.app.job.JobInfo.Builder#setClipData(ClipData, int) . Will be 0 if it was not set. |
getExtras
open fun getExtras(): PersistableBundle
Return | |
---|---|
PersistableBundle |
The extras you passed in when constructing this job with android.app.job.JobInfo.Builder#setExtras(android.os.PersistableBundle) . This will never be null. If you did not set any extras this will be an empty bundle. |
getJobId
open fun getJobId(): Int
Return | |
---|---|
Int |
The unique id of this job, specified at creation time. |
getJobNamespace
open fun getJobNamespace(): String?
Get the namespace this job was placed in.
Return | |
---|---|
String? |
The namespace this job was scheduled in. Will be null if there was no explicit namespace set and this job is therefore in the default namespace. |
getNetwork
open fun getNetwork(): Network?
Return the network that should be used to perform any network requests for this job.
Devices may have multiple active network connections simultaneously, or they may not have a default network route at all. To correctly handle all situations like this, your job should always use the network returned by this method instead of implicitly using the default network route.
Note that the system may relax the constraints you originally requested, such as allowing a JobInfo#NETWORK_TYPE_UNMETERED
job to run over a metered network when there is a surplus of metered data available. Starting in Android version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE
, this will return null
if the app does not hold the permissions specified in JobInfo.Builder#setRequiredNetwork(NetworkRequest)
.
Return | |
---|---|
Network? |
the network that should be used to perform any network requests for this job, or null if this job didn't set any required network type or if the job executed when there was no available network to use. |
getStopReason
open fun getStopReason(): Int
getTransientExtras
open fun getTransientExtras(): Bundle
Return | |
---|---|
Bundle |
The transient extras you passed in when constructing this job with android.app.job.JobInfo.Builder#setTransientExtras(android.os.Bundle) . This will never be null. If you did not set any extras this will be an empty bundle. |
getTriggeredContentAuthorities
open fun getTriggeredContentAuthorities(): Array<String!>?
For jobs with android.app.job.JobInfo.Builder#addTriggerContentUri
set, this reports which content authorities have triggered the job. It will only be null if no authorities have triggered it -- that is, the job executed for some other reason, such as a deadline expiring. If this is non-null, you can use getTriggeredContentUris()
to retrieve the details of which URIs changed (as long as that has not exceeded the maximum number it can reported).
getTriggeredContentUris
open fun getTriggeredContentUris(): Array<Uri!>?
For jobs with android.app.job.JobInfo.Builder#addTriggerContentUri
set, this reports which URIs have triggered the job. This will be null if either no URIs have triggered it (it went off due to a deadline or other reason), or the number of changed URIs is too large to report. Whether or not the number of URIs is too large, you can always use getTriggeredContentAuthorities()
to determine whether the job was triggered due to any content changes and the authorities they are associated with.
isExpeditedJob
open fun isExpeditedJob(): Boolean
Return | |
---|---|
Boolean |
Whether this job is running as an expedited job or not. A job is guaranteed to have all expedited job guarantees for the duration of the job execution if this returns true . This will return false if the job that wasn't requested to run as a expedited job, or if it was requested to run as an expedited job but the app didn't have any remaining expedited job quota at the time of execution. |
isOverrideDeadlineExpired
open fun isOverrideDeadlineExpired(): Boolean
For jobs with android.app.job.JobInfo.Builder#setOverrideDeadline(long)
set, this provides an easy way to tell whether the job is being executed due to the deadline expiring. Note: If the job is running because its deadline expired, it implies that its constraints will not be met. However, periodic jobs
will only ever run when their constraints are satisfied, therefore, the constraints will still be satisfied for a periodic job even if the deadline has expired.
isUserInitiatedJob
open fun isUserInitiatedJob(): Boolean
Return | |
---|---|
Boolean |
Whether this job is running as a user-initiated job or not. A job is guaranteed to have all user-initiated job guarantees for the duration of the job execution if this returns true . This will return false if the job wasn't requested to run as a user-initiated job, or if it was requested to run as a user-initiated job but the app didn't meet any of the requirements at the time of execution, such as having the android.Manifest.permission#RUN_USER_INITIATED_JOBS permission. |
writeToParcel
open fun writeToParcel(
dest: Parcel,
flags: Int
): Unit
Parameters | |
---|---|
dest |
Parcel: The Parcel in which the object should be written. This value cannot be null . |
flags |
Int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE . Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |