Introduce "IdleService" API to expose idle-time maintenance to apps
When an application wishes to do low-priority background work when the
device is otherwise idle (e.g. in a desk dock overnight), it declares
a service in its manifest that requires this permission:
android:permission="android.permission.BIND_IDLE_SERVICE
to launch, and which publishes this intent filter:
<intent-filter>
<action android:name="android.service.idle.IdleService" />
</intent-filter>
This string is declared in the API as IdleService.SERVICE_INTERFACE.
The service must be implemented by extending the new "IdleService"
class, which provides the API through which the system will communicate
with the app.
IdleService declares three methods, two of which are lifecycle callbacks
to the service, and the third of which is for the service itself to
invoke when appropriate. The lifecycle callbacks are
public abstract boolean onIdleStart();
public abstract void onIdleStop();
The first of these is a notification to the service that an idle
maintenance interval has begun. The service can then spin off
whatever non-UI work it wishes. When the interval is over, or if
the OS determines that idle services should be shut down immediately,
the onIdleStop() method will be invoked. The service must shut down
any background processing immediately when this method is called.
Both of these methods must return immediately. However, the OS
holds a wakelock on the application's behalf for the entire period
between the onIdleStart() and onIdleStop() callbacks. This means
that for system-arbitrated idle-time operation, the application does
not need to do any of its own wakelock management, and does not need
to hold any wakelock permissions.
The third method in IdleService is
public final void finishIdle();
Calling this method notifies the OS that the application has finished
whatever idle-time operation it needed to perform, and the OS is thus
free to release the wakelock and return to normal operation (or to
allow other apps to run their own idle services).
Currently the idle window granted to each idle service is ten minutes.
The OS is rather conservative about when these services are run; low
battery or any user activity will suppress them, and the OS will not
choose to run them particularly often.
Idle services are granted their execution windows in round-robin
fashion.
Bug 9680213
Change-Id: Idd6f35940c938c31b94aa4269a67870abf7125b6
diff --git a/core/java/android/app/maintenance/IIdleCallback.aidl b/core/java/android/app/maintenance/IIdleCallback.aidl
new file mode 100644
index 0000000..582dede
--- /dev/null
+++ b/core/java/android/app/maintenance/IIdleCallback.aidl
@@ -0,0 +1,53 @@
+/**
+ * Copyright 2014, The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.app.maintenance;
+
+import android.app.maintenance.IIdleService;
+
+/**
+ * The server side of the idle maintenance IPC protocols. The app-side implementation
+ * invokes on this interface to indicate completion of the (asynchronous) instructions
+ * issued by the server.
+ *
+ * In all cases, the 'who' parameter is the caller's service binder, used to track
+ * which idle service instance is reporting.
+ *
+ * {@hide}
+ */
+interface IIdleCallback {
+ /**
+ * Acknowledge receipt and processing of the asynchronous "start idle work" incall.
+ * 'result' is true if the app wants some time to perform ongoing background
+ * idle-time work; or false if the app declares that it does not need any time
+ * for such work.
+ */
+ void acknowledgeStart(int token, boolean result);
+
+ /**
+ * Acknowledge receipt and processing of the asynchronous "stop idle work" incall.
+ */
+ void acknowledgeStop(int token);
+
+ /*
+ * Tell the idle service manager that we're done with our idle maintenance, so that
+ * it can go on to the next one and stop attributing wakelock time to us etc.
+ *
+ * @param opToken The identifier passed in the startIdleMaintenance() call that
+ * indicated the beginning of this service's idle timeslice.
+ */
+ void idleFinished(int token);
+}