16e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams/* 26e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * Copyright (C) 2014 The Android Open Source Project 36e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * 46e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * Licensed under the Apache License, Version 2.0 (the "License"); 56e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * you may not use this file except in compliance with the License. 66e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * You may obtain a copy of the License at 76e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * 86e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * http://www.apache.org/licenses/LICENSE-2.0 96e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * 106e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * Unless required by applicable law or agreed to in writing, software 116e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * distributed under the License is distributed on an "AS IS" BASIS, 126e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 136e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * See the License for the specific language governing permissions and 146e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * limitations under the License 156e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams */ 166e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 177060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tatepackage android.app.job; 186e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 19f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackbornimport android.annotation.NonNull; 20f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackbornimport android.annotation.Nullable; 217060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tateimport android.app.job.IJobCallback; 22a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackbornimport android.content.ClipData; 2376a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkeyimport android.net.Network; 241a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackbornimport android.net.Uri; 25ba60473a6539d16bef8720d79b5559512303bddfDianne Hackbornimport android.os.Bundle; 266e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williamsimport android.os.IBinder; 276e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williamsimport android.os.Parcel; 286e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williamsimport android.os.Parcelable; 293d86fd2bb9db6067c49634bc4c6cdb4d5235ad36Matthew Williamsimport android.os.PersistableBundle; 307da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackbornimport android.os.RemoteException; 316e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 326e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams/** 337060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate * Contains the parameters used to configure/identify your job. You do not create this object 346e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * yourself, instead it is handed in to your application by the System. 356e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams */ 367060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tatepublic class JobParameters implements Parcelable { 376e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 385db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge /** @hide */ 3933a412b52d49c15e2948f3392b7c619c4e3e308dTej Singh public static final int REASON_CANCELED = JobProtoEnums.STOP_REASON_CANCELLED; // 0. 405db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge /** @hide */ 4133a412b52d49c15e2948f3392b7c619c4e3e308dTej Singh public static final int REASON_CONSTRAINTS_NOT_SATISFIED = 4233a412b52d49c15e2948f3392b7c619c4e3e308dTej Singh JobProtoEnums.STOP_REASON_CONSTRAINTS_NOT_SATISFIED; //1. 435db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge /** @hide */ 4433a412b52d49c15e2948f3392b7c619c4e3e308dTej Singh public static final int REASON_PREEMPT = JobProtoEnums.STOP_REASON_PREEMPT; // 2. 455db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge /** @hide */ 4633a412b52d49c15e2948f3392b7c619c4e3e308dTej Singh public static final int REASON_TIMEOUT = JobProtoEnums.STOP_REASON_TIMEOUT; // 3. 475db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge /** @hide */ 4833a412b52d49c15e2948f3392b7c619c4e3e308dTej Singh public static final int REASON_DEVICE_IDLE = JobProtoEnums.STOP_REASON_DEVICE_IDLE; // 4. 495db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge 5094326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn /** @hide */ 5194326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn public static String getReasonName(int reason) { 5294326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn switch (reason) { 5394326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn case REASON_CANCELED: return "canceled"; 5494326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn case REASON_CONSTRAINTS_NOT_SATISFIED: return "constraints"; 5594326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn case REASON_PREEMPT: return "preempt"; 5694326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn case REASON_TIMEOUT: return "timeout"; 5794326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn case REASON_DEVICE_IDLE: return "device_idle"; 5894326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn default: return "unknown:" + reason; 5994326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn } 6094326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn } 6194326cb56aa0c7cee110d6781fb8b8f16fb09663Dianne Hackborn 627060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate private final int jobId; 633d86fd2bb9db6067c49634bc4c6cdb4d5235ad36Matthew Williams private final PersistableBundle extras; 64ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn private final Bundle transientExtras; 65a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn private final ClipData clipData; 66a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn private final int clipGrantFlags; 676de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams private final IBinder callback; 6803a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams private final boolean overrideDeadlineExpired; 691a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn private final Uri[] mTriggeredContentUris; 701a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn private final String[] mTriggeredContentAuthorities; 7176a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey private final Network network; 721a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn 735db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge private int stopReason; // Default value of stopReason is REASON_CANCELED 74d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki private String debugStopReason; // Human readable stop reason for debugging. 756de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams 766de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams /** @hide */ 7703a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams public JobParameters(IBinder callback, int jobId, PersistableBundle extras, 78a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn Bundle transientExtras, ClipData clipData, int clipGrantFlags, 79a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn boolean overrideDeadlineExpired, Uri[] triggeredContentUris, 8076a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey String[] triggeredContentAuthorities, Network network) { 817060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate this.jobId = jobId; 826de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams this.extras = extras; 83ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn this.transientExtras = transientExtras; 84a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn this.clipData = clipData; 85a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn this.clipGrantFlags = clipGrantFlags; 866de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams this.callback = callback; 8703a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams this.overrideDeadlineExpired = overrideDeadlineExpired; 881a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn this.mTriggeredContentUris = triggeredContentUris; 891a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn this.mTriggeredContentAuthorities = triggeredContentAuthorities; 9076a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey this.network = network; 916de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams } 926e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 936e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams /** 947060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate * @return The unique id of this job, specified at creation time. 956e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams */ 967060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate public int getJobId() { 977060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate return jobId; 986e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 996e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 1006e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams /** 1015db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge * Reason onStopJob() was called on this job. 1025db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge * @hide 1035db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge */ 1045db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge public int getStopReason() { 1055db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge return stopReason; 1065db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge } 1075db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge 1085db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge /** 109d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki * Reason onStopJob() was called on this job. 110d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki * @hide 111d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki */ 112d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki public String getDebugStopReason() { 113d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki return debugStopReason; 114d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki } 115d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki 116d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki /** 1177060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate * @return The extras you passed in when constructing this job with 1187060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate * {@link android.app.job.JobInfo.Builder#setExtras(android.os.PersistableBundle)}. This will 1196e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams * never be null. If you did not set any extras this will be an empty bundle. 1206e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams */ 121f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackborn public @NonNull PersistableBundle getExtras() { 1226e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams return extras; 1236e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 1246e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 12503a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams /** 126ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn * @return The transient extras you passed in when constructing this job with 127ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn * {@link android.app.job.JobInfo.Builder#setTransientExtras(android.os.Bundle)}. This will 128ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn * never be null. If you did not set any extras this will be an empty bundle. 129ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn */ 130f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackborn public @NonNull Bundle getTransientExtras() { 131ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn return transientExtras; 132ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn } 133ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn 134ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn /** 135a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn * @return The clip you passed in when constructing this job with 136a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn * {@link android.app.job.JobInfo.Builder#setClipData(ClipData, int)}. Will be null 137a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn * if it was not set. 138a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn */ 139f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackborn public @Nullable ClipData getClipData() { 140a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn return clipData; 141a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn } 142a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn 143a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn /** 144a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn * @return The clip grant flags you passed in when constructing this job with 145a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn * {@link android.app.job.JobInfo.Builder#setClipData(ClipData, int)}. Will be 0 146a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn * if it was not set. 147a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn */ 148a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn public int getClipGrantFlags() { 149a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn return clipGrantFlags; 150a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn } 151a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn 152a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn /** 15303a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams * For jobs with {@link android.app.job.JobInfo.Builder#setOverrideDeadline(long)} set, this 15403a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams * provides an easy way to tell whether the job is being executed due to the deadline 15503a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams * expiring. Note: If the job is running because its deadline expired, it implies that its 15603a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams * constraints will not be met. 15703a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams */ 15803a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams public boolean isOverrideDeadlineExpired() { 15903a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams return overrideDeadlineExpired; 16003a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams } 16103a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams 1621a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn /** 1631a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * For jobs with {@link android.app.job.JobInfo.Builder#addTriggerContentUri} set, this 1641a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * reports which URIs have triggered the job. This will be null if either no URIs have 1651a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * triggered it (it went off due to a deadline or other reason), or the number of changed 1661a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * URIs is too large to report. Whether or not the number of URIs is too large, you can 1671a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * always use {@link #getTriggeredContentAuthorities()} to determine whether the job was 1681a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * triggered due to any content changes and the authorities they are associated with. 1691a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn */ 170f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackborn public @Nullable Uri[] getTriggeredContentUris() { 1711a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn return mTriggeredContentUris; 1721a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn } 1731a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn 1741a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn /** 1751a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * For jobs with {@link android.app.job.JobInfo.Builder#addTriggerContentUri} set, this 1761a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * reports which content authorities have triggered the job. It will only be null if no 1771a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * authorities have triggered it -- that is, the job executed for some other reason, such 1781a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * as a deadline expiring. If this is non-null, you can use {@link #getTriggeredContentUris()} 1791a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * to retrieve the details of which URIs changed (as long as that has not exceeded the maximum 1801a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn * number it can reported). 1811a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn */ 182f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackborn public @Nullable String[] getTriggeredContentAuthorities() { 1831a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn return mTriggeredContentAuthorities; 1841a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn } 1851a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn 1867da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn /** 18776a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * Return the network that should be used to perform any network requests 18876a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * for this job. 18976a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * <p> 19076a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * Devices may have multiple active network connections simultaneously, or 19176a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * they may not have a default network route at all. To correctly handle all 19276a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * situations like this, your job should always use the network returned by 19376a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * this method instead of implicitly using the default network route. 19476a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * <p> 19576a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * Note that the system may relax the constraints you originally requested, 19676a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * such as allowing a {@link JobInfo#NETWORK_TYPE_UNMETERED} job to run over 19776a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * a metered network when there is a surplus of metered data available. 19876a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * 19976a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * @return the network that should be used to perform any network requests 20076a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * for this job, or {@code null} if this job didn't set any required 20176a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * network type. 20276a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey * @see JobInfo.Builder#setRequiredNetworkType(int) 20376a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey */ 20476a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey public @Nullable Network getNetwork() { 20576a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey return network; 20676a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey } 20776a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey 20876a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey /** 2097da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * Dequeue the next pending {@link JobWorkItem} from these JobParameters associated with their 2107da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * currently running job. Calling this method when there is no more work available and all 2117da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * previously dequeued work has been completed will result in the system taking care of 2127da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * stopping the job for you -- 2137da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * you should not call {@link JobService#jobFinished(JobParameters, boolean)} yourself 2147da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * (otherwise you risk losing an upcoming JobWorkItem that is being enqueued at the same time). 2157da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * 216fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * <p>Once you are done with the {@link JobWorkItem} returned by this method, you must call 217fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * {@link #completeWork(JobWorkItem)} with it to inform the system that you are done 218fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * executing the work. The job will not be finished until all dequeued work has been 219fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * completed. You do not, however, have to complete each returned work item before deqeueing 220fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * the next one -- you can use {@link #dequeueWork()} multiple times before completing 221fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * previous work if you want to process work in parallel, and you can complete the work 222fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * in whatever order you want.</p> 223fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * 224fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * <p>If the job runs to the end of its available time period before all work has been 225fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * completed, it will stop as normal. You should return true from 226fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * {@link JobService#onStopJob(JobParameters)} in order to have the job rescheduled, and by 227fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * doing so any pending as well as remaining uncompleted work will be re-queued 228fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * for the next time the job runs.</p> 229fd8807accf8ac811818e016fcd4c3dd6e165d379Dianne Hackborn * 23028d1b661347a6a7e05dc1004fd7e8436cace8953Dianne Hackborn * <p>This example shows how to construct a JobService that will serially dequeue and 23128d1b661347a6a7e05dc1004fd7e8436cace8953Dianne Hackborn * process work that is available for it:</p> 23228d1b661347a6a7e05dc1004fd7e8436cace8953Dianne Hackborn * 23328d1b661347a6a7e05dc1004fd7e8436cace8953Dianne Hackborn * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/JobWorkService.java 23428d1b661347a6a7e05dc1004fd7e8436cace8953Dianne Hackborn * service} 23528d1b661347a6a7e05dc1004fd7e8436cace8953Dianne Hackborn * 2367da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * @return Returns a new {@link JobWorkItem} if there is one pending, otherwise null. 2377da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * If null is returned, the system will also stop the job if all work has also been completed. 2387da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * (This means that for correct operation, you must always call dequeueWork() after you have 2397da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * completed other work, to check either for more work or allow the system to stop the job.) 2407da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn */ 241f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackborn public @Nullable JobWorkItem dequeueWork() { 2427da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn try { 2437da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn return getCallback().dequeueWork(getJobId()); 2447da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn } catch (RemoteException e) { 2457da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn throw e.rethrowFromSystemServer(); 2467da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn } 2477da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn } 2487da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn 2497da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn /** 2507da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * Report the completion of executing a {@link JobWorkItem} previously returned by 2517da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * {@link #dequeueWork()}. This tells the system you are done with the 2527da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * work associated with that item, so it will not be returned again. Note that if this 2537da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * is the last work in the queue, completing it here will <em>not</em> finish the overall 2547da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * job -- for that to happen, you still need to call {@link #dequeueWork()} 2557da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * again. 2567da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * 2577da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * <p>If you are enqueueing work into a job, you must call this method for each piece 2587da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * of work you process. Do <em>not</em> call 2597da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * {@link JobService#jobFinished(JobParameters, boolean)} 2607da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * or else you can lose work in your queue.</p> 2617da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * 2627da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * @param work The work you have completed processing, as previously returned by 2637da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn * {@link #dequeueWork()} 2647da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn */ 265f9bac16d61db0fceb15484587ecf876c2b802c37Dianne Hackborn public void completeWork(@NonNull JobWorkItem work) { 2667da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn try { 2677da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn if (!getCallback().completeWork(getJobId(), work.getWorkId())) { 2687da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn throw new IllegalArgumentException("Given work is not active: " + work); 2697da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn } 2707da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn } catch (RemoteException e) { 2717da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn throw e.rethrowFromSystemServer(); 2727da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn } 2737da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn } 2747da13d7c3e5b48c0410ae869c5679652de97e5aaDianne Hackborn 2756de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams /** @hide */ 2767060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate public IJobCallback getCallback() { 2777060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate return IJobCallback.Stub.asInterface(callback); 2786e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 2796e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 2807060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate private JobParameters(Parcel in) { 2817060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate jobId = in.readInt(); 2823d86fd2bb9db6067c49634bc4c6cdb4d5235ad36Matthew Williams extras = in.readPersistableBundle(); 283ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn transientExtras = in.readBundle(); 284a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn if (in.readInt() != 0) { 285a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn clipData = ClipData.CREATOR.createFromParcel(in); 286a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn clipGrantFlags = in.readInt(); 287a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn } else { 288a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn clipData = null; 289a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn clipGrantFlags = 0; 290a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn } 2916de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams callback = in.readStrongBinder(); 29203a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams overrideDeadlineExpired = in.readInt() == 1; 2931a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn mTriggeredContentUris = in.createTypedArray(Uri.CREATOR); 2941a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn mTriggeredContentAuthorities = in.createStringArray(); 29576a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey if (in.readInt() != 0) { 29676a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey network = Network.CREATOR.createFromParcel(in); 29776a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey } else { 29876a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey network = null; 29976a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey } 3005db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge stopReason = in.readInt(); 301d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki debugStopReason = in.readString(); 3025db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge } 3035db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge 3045db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge /** @hide */ 305d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki public void setStopReason(int reason, String debugStopReason) { 3065db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge stopReason = reason; 307d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki this.debugStopReason = debugStopReason; 3086e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 3096e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 3106e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams @Override 3116e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams public int describeContents() { 3126e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams return 0; 3136e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 3146e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 3156e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams @Override 3166e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams public void writeToParcel(Parcel dest, int flags) { 3177060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate dest.writeInt(jobId); 3183d86fd2bb9db6067c49634bc4c6cdb4d5235ad36Matthew Williams dest.writePersistableBundle(extras); 319ba60473a6539d16bef8720d79b5559512303bddfDianne Hackborn dest.writeBundle(transientExtras); 320a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn if (clipData != null) { 321a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn dest.writeInt(1); 322a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn clipData.writeToParcel(dest, flags); 323a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn dest.writeInt(clipGrantFlags); 324a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn } else { 325a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn dest.writeInt(0); 326a47223f99b6b7ade4ae909c458d975eb487062b3Dianne Hackborn } 3276de79e2b17fa0796ea4d39fd9555b563c484248dMatthew Williams dest.writeStrongBinder(callback); 32803a4da6e8e92b19c1345016c06694cb3aabbfc27Matthew Williams dest.writeInt(overrideDeadlineExpired ? 1 : 0); 3291a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn dest.writeTypedArray(mTriggeredContentUris, flags); 3301a30bd9b13fd127d9bbfdc5fd4cb2f80ab7ece21Dianne Hackborn dest.writeStringArray(mTriggeredContentAuthorities); 33176a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey if (network != null) { 33276a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey dest.writeInt(1); 33376a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey network.writeToParcel(dest, flags); 33476a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey } else { 33576a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey dest.writeInt(0); 33676a0241effeb80cb3bdd15be3efbfa84b6172d6eJeff Sharkey } 3375db09084c8e4efc6311754243c39962fc8e7a766Shreyas Basarge dest.writeInt(stopReason); 338d2bfec6359654b14e627502b784131cff1ebf03dMakoto Onuki dest.writeString(debugStopReason); 3396e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 3406e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 3417060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate public static final Creator<JobParameters> CREATOR = new Creator<JobParameters>() { 3426e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams @Override 3437060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate public JobParameters createFromParcel(Parcel in) { 3447060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate return new JobParameters(in); 3456e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 3466e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams 3476e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams @Override 3487060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate public JobParameters[] newArray(int size) { 3497060b04f6d92351b67222e636ab378a0273bf3e7Christopher Tate return new JobParameters[size]; 3506e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams } 3516e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams }; 3526e31c5c82bc5c9bddf9c01d254067ea5bebbd96bMatthew Williams} 353