Fix API review: Camera prewarm

Let the intent receiver of a camea launch intent declare a prewarm
service instead of sending broadcasts.

Bug: 21347653
Change-Id: I11e31aad4f788ad90eb46a661b819d3e808ddb51

2 files changed, 112 insertions, 24 deletions

diff --git a/core/java/android/provider/MediaStore.java b/core/java/android/provider/MediaStore.java
index 7565654b..51dbdee 100644
--- a/core/java/android/provider/MediaStore.java
+++ b/core/java/android/provider/MediaStore.java
@@ -22,6 +22,7 @@ import android.content.ContentResolver;
 import android.content.ContentUris;
 import android.content.ContentValues;
 import android.content.Context;
+import android.content.Intent;
 import android.database.Cursor;
 import android.database.DatabaseUtils;
 import android.database.sqlite.SQLiteException;
@@ -33,6 +34,7 @@ import android.media.ThumbnailUtils;
 import android.net.Uri;
 import android.os.Environment;
 import android.os.ParcelFileDescriptor;
+import android.service.media.CameraPrewarmService;
 import android.util.Log;
 
 import java.io.FileInputStream;
@@ -226,33 +228,24 @@ public final class MediaStore {
     public static final String INTENT_ACTION_STILL_IMAGE_CAMERA = "android.media.action.STILL_IMAGE_CAMERA";
 
     /**
-     * The name of the Intent action used to indicate that a camera launch might be imminent. This
-     * broadcast should be targeted to the package that is receiving
-     * {@link #INTENT_ACTION_STILL_IMAGE_CAMERA} or
-     * {@link #INTENT_ACTION_STILL_IMAGE_CAMERA_SECURE}, depending on the context. If such
-     * intent would launch the resolver activity, this broadcast should not be sent at all.
+     * Name under which an activity handling {@link #INTENT_ACTION_STILL_IMAGE_CAMERA} or
+     * {@link #INTENT_ACTION_STILL_IMAGE_CAMERA_SECURE} publishes the service name for its prewarm
+     * service.
      * <p>
-     * A receiver of this broadcast should do the absolute minimum amount of work to initialize the
-     * camera in order to reduce startup time in likely case that shortly after an actual camera
-     * launch intent would be sent.
+     * This meta-data should reference the fully qualified class name of the prewarm service
+     * extending {@link CameraPrewarmService}.
      * <p>
-     * In case the actual intent will not be fired, the target package will receive
-     * {@link #ACTION_STILL_IMAGE_CAMERA_COOLDOWN}. However, it is recommended that the receiver
-     * also implements a timeout to close the camera after receiving this intent, as there is no
-     * guarantee that {@link #ACTION_STILL_IMAGE_CAMERA_COOLDOWN} will be delivered.
-     */
-    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
-    public static final String ACTION_STILL_IMAGE_CAMERA_PREWARM = "android.media.action.STILL_IMAGE_CAMERA_PREWARM";
-
-    /**
-     * The name of the Intent action used to indicate that an imminent camera launch has been
-     * cancelled by the user. This broadcast should be targeted to the package that has received
-     * {@link #ACTION_STILL_IMAGE_CAMERA_PREWARM}.
+     * The prewarm service will get bound and receive a prewarm signal
+     * {@link CameraPrewarmService#onPrewarm()} when a camera launch intent fire might be imminent.
+     * An application implementing a prewarm service should do the absolute minimum amount of work
+     * to initialize the camera in order to reduce startup time in likely case that shortly after a
+     * camera launch intent would be sent.
      * <p>
-     * A receiver of this broadcast should close the camera immediately.
+     * If the camera launch intent gets fired shortly after, the service will be unbound
+     * asynchronously, without receiving
      */
-    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
-    public static final String ACTION_STILL_IMAGE_CAMERA_COOLDOWN = "android.media.action.STILL_IMAGE_CAMERA_COOLDOWN";
+    public static final String META_DATA_STILL_IMAGE_CAMERA_PREWARM_SERVICE =
+            "android.media.still_image_camera_preview_service";
 
     /**
      * The name of the Intent action used to launch a camera in still image mode
@@ -2268,5 +2261,4 @@ public final class MediaStore {
         }
         return null;
     }
-
 }
diff --git a/core/java/android/service/media/CameraPrewarmService.java b/core/java/android/service/media/CameraPrewarmService.java
new file mode 100644
index 0000000..335b00a
--- /dev/null
+++ b/core/java/android/service/media/CameraPrewarmService.java
@@ -0,0 +1,96 @@
+/*
+ * Copyright (C) 2015 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.service.media;
+
+import android.app.Service;
+import android.content.Intent;
+import android.os.Handler;
+import android.os.IBinder;
+import android.os.Message;
+import android.os.Messenger;
+
+/**
+ * Extend this class to implement a camera prewarm service. See
+ * {@link android.provider.MediaStore#META_DATA_STILL_IMAGE_CAMERA_PREWARM_SERVICE}.
+ */
+public abstract class CameraPrewarmService extends Service {
+
+    /**
+     * Intent action to bind the service as a prewarm service.
+     * @hide
+     */
+    public static final String ACTION_PREWARM =
+            "android.service.media.CameraPrewarmService.ACTION_PREWARM";
+
+    /**
+     * Message sent by the client indicating that the camera intent has been fired.
+     * @hide
+     */
+    public static final int MSG_CAMERA_FIRED = 1;
+
+    private final Handler mHandler = new Handler() {
+
+        @Override
+        public void handleMessage(Message msg) {
+            switch (msg.what) {
+                case MSG_CAMERA_FIRED:
+                    mCameraIntentFired = true;
+                    break;
+                default:
+                    super.handleMessage(msg);
+            }
+        }
+    };
+    private boolean mCameraIntentFired;
+
+    @Override
+    public IBinder onBind(Intent intent) {
+        if (ACTION_PREWARM.equals(intent.getAction())) {
+            onPrewarm();
+            return new Messenger(mHandler).getBinder();
+        } else {
+            return null;
+        }
+    }
+
+    @Override
+    public boolean onUnbind(Intent intent) {
+        if (ACTION_PREWARM.equals(intent.getAction())) {
+            onCooldown(mCameraIntentFired);
+        }
+        return false;
+    }
+
+    /**
+     * Called when the camera should be prewarmed.
+     */
+    public abstract void onPrewarm();
+
+    /**
+     * Called when prewarm phase is done, either because the camera launch intent has been fired
+     * at this point or prewarm is no longer needed. A client should close the camera
+     * immediately in the latter case.
+     * <p>
+     * In case the camera launch intent has been fired, there is no guarantee about the ordering
+     * of these two events. Cooldown might happen either before or after the activity has been
+     * created that handles the camera intent.
+     *
+     * @param cameraIntentFired Indicates whether the intent to launch the camera has been
+     *                          fired.
+     */
+    public abstract void onCooldown(boolean cameraIntentFired);
+}