JobScheduler.Enqueue(JobInfo, JobWorkItem) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Similar to #schedule, but allows you to enqueue work for a new <em>or existing</em>
job.
[Android.Runtime.Register("enqueue", "(Landroid/app/job/JobInfo;Landroid/app/job/JobWorkItem;)I", "GetEnqueue_Landroid_app_job_JobInfo_Landroid_app_job_JobWorkItem_Handler", ApiSince=26)]
public abstract int Enqueue (Android.App.Job.JobInfo job, Android.App.Job.JobWorkItem work);[<Android.Runtime.Register("enqueue", "(Landroid/app/job/JobInfo;Landroid/app/job/JobWorkItem;)I", "GetEnqueue_Landroid_app_job_JobInfo_Landroid_app_job_JobWorkItem_Handler", ApiSince=26)>]
abstract member Enqueue : Android.App.Job.JobInfo * Android.App.Job.JobWorkItem -> intParameters
- job
- JobInfo
The job you wish to enqueue work for. See
android.app.job.JobInfo.Builder JobInfo.Builder for more detail on the sorts of jobs
you can schedule.
- work
- JobWorkItem
New work to enqueue. This will be available later when the job starts running.
Returns
the result of the enqueue request.
- Attributes
Remarks
Similar to #schedule, but allows you to enqueue work for a new <em>or existing</em> job. If a job with the same ID is already scheduled, it will be replaced with the new JobInfo, but any previously enqueued work will remain and be dispatched the next time it runs. If a job with the same ID is already running, the new work will be enqueued for it without stopping the job.
The work you enqueue is later retrieved through JobParameters#dequeueWork() JobParameters.dequeueWork. Be sure to see there about how to process work; the act of enqueueing work changes how you should handle the overall lifecycle of an executing job.
It is strongly encouraged that you use the same JobInfo for all work you enqueue. This will allow the system to optimally schedule work along with any pending and/or currently running work. If the JobInfo changes from the last time the job was enqueued, the system will need to update the associated JobInfo, which can cause a disruption in execution. In particular, this can result in any currently running job that is processing previous work to be stopped and restarted with the new JobInfo.
It is recommended that you avoid using JobInfo.Builder#setExtras(PersistableBundle) or JobInfo.Builder#setTransientExtras(Bundle) with a JobInfo you are using to enqueue work. The system will try to compare these extras with the previous JobInfo, but there are situations where it may get this wrong and count the JobInfo as changing. (That said, you should be relatively safe with a simple set of consistent data in these fields.) You should never use JobInfo.Builder#setClipData(ClipData, int) with work you are enqueuing, since currently this will always be treated as a different JobInfo, even if the ClipData contents are exactly the same.
<p class="caution"><strong>Note:</strong> Scheduling a job can have a high cost, even if it's rescheduling the same job and the job didn't execute, especially on platform versions before version android.os.Build.VERSION_CODES#Q. As such, the system may throttle calls to this API if calls are made too frequently in a short amount of time.
<p class="caution"><strong>Note:</strong> Prior to Android version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, JobWorkItems could not be persisted. Apps were not allowed to enqueue JobWorkItems with persisted jobs and the system would throw an IllegalArgumentException if they attempted to do so. Starting with android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, JobWorkItems can be persisted alongside the hosting job. However, Intents cannot be persisted. Set a PersistableBundle using JobWorkItem.Builder#setExtras(PersistableBundle) for any information that needs to be persisted.
Note: The JobService component needs to be enabled in order to successfully schedule a job.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.