xref: /frameworks/ex/camera2/public/src/com/android/ex/camera2/blocking/BlockingCameraManager.java

/*
 * Copyright 2013 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 com.android.ex.camera2.blocking;

import android.hardware.camera2.CameraAccessException;
import android.hardware.camera2.CameraDevice;
import android.hardware.camera2.CameraManager;
import android.os.ConditionVariable;
import android.os.Handler;
import android.os.Looper;
import android.util.Log;

import com.android.ex.camera2.exceptions.TimeoutRuntimeException;

import java.util.Objects;

/**
 * Expose {@link CameraManager} functionality with blocking functions.
 *
 * <p>Safe to use at the same time as the regular CameraManager, so this does not
 * duplicate any functionality that is already blocking.</p>
 *
 * <p>Be careful when using this from UI thread! This function will typically block
 * for about 500ms when successful, and as long as {@value #OPEN_TIME_OUT_MS}ms when timing out.</p>
 */
public class BlockingCameraManager {

    private static final String TAG = "BlockingCameraManager";
    private static final boolean VERBOSE = Log.isLoggable(TAG, Log.VERBOSE);

    private static final int OPEN_TIME_OUT_MS = 2000; // ms time out for openCamera

    /**
     * Exception thrown by {@link #openCamera} if the open fails asynchronously.
     */
    public static class BlockingOpenException extends Exception {
        /**
         * Suppress Eclipse warning
         */
        private static final long serialVersionUID = 12397123891238912L;

        public static final int ERROR_DISCONNECTED = 0; // Does not clash with ERROR_...

        private final int mError;

        public boolean wasDisconnected() {
            return mError == ERROR_DISCONNECTED;
        }

        public boolean wasError() {
            return mError != ERROR_DISCONNECTED;
        }

        /**
         * Returns the error code {@link ERROR_DISCONNECTED} if disconnected, or one of
         * {@code CameraDevice.StateCallback#ERROR_*} if there was another error.
         *
         * @return int Disconnect/error code
         */
        public int getCode() {
            return mError;
        }

        /**
         * Thrown when camera device enters error state during open, or if
         * it disconnects.
         *
         * @param errorCode
         * @param message
         *
         * @see {@link CameraDevice.StateCallback#ERROR_CAMERA_DEVICE}
         */
        public BlockingOpenException(int errorCode, String message) {
            super(message);
            mError = errorCode;
        }
    }

    private final CameraManager mManager;

    /**
     * Create a new blocking camera manager.
     *
     * @param manager
     *            CameraManager returned by
     *            {@code Context.getSystemService(Context.CAMERA_SERVICE)}
     */
    public BlockingCameraManager(CameraManager manager) {
        if (manager == null) {
            throw new IllegalArgumentException("manager must not be null");
        }
        mManager = manager;
    }

    /**
     * Open the camera, blocking it until it succeeds or fails.
     *
     * <p>Note that the Handler provided must not be null. Furthermore, if there is a handler,
     * its Looper must not be the current thread's Looper. Otherwise we'd never receive
     * the callbacks from the CameraDevice since this function would prevent them from being
     * processed.</p>
     *
     * <p>Throws {@link CameraAccessException} for the same reason {@link CameraManager#openCamera}
     * does.</p>
     *
     * <p>Throws {@link BlockingOpenException} when the open fails asynchronously (due to
     * {@link CameraDevice.StateCallback#onDisconnected(CameraDevice)} or
     * ({@link CameraDevice.StateCallback#onError(CameraDevice)}.</p>
     *
     * <p>Throws {@link TimeoutRuntimeException} if opening times out. This is usually
     * highly unrecoverable, and all future calls to opening that camera will fail since the
     * service will think it's busy. This class will do its best to clean up eventually.</p>
     *
     * @param cameraId
     *            Id of the camera
     * @param listener
     *            Listener to the camera. onOpened, onDisconnected, onError need not be implemented.
     * @param handler
     *            Handler which to run the listener on. Must not be null.
     *
     * @return CameraDevice
     *
     * @throws IllegalArgumentException
     *            If the handler is null, or if the handler's looper is current.
     * @throws CameraAccessException
     *            If open fails immediately.
     * @throws BlockingOpenException
     *            If open fails after blocking for some amount of time.
     * @throws TimeoutRuntimeException
     *            If opening times out. Typically unrecoverable.
     */
    public CameraDevice openCamera(String cameraId, CameraDevice.StateCallback listener,
            Handler handler) throws CameraAccessException, BlockingOpenException {

        if (handler == null) {
            throw new IllegalArgumentException("handler must not be null");
        } else if (handler.getLooper() == Looper.myLooper()) {
            throw new IllegalArgumentException("handler's looper must not be the current looper");
        }

        return (new OpenListener(mManager, cameraId, listener, handler)).blockUntilOpen();
    }

    private static void assertEquals(Object a, Object b) {
        if (!Objects.equals(a, b)) {
            throw new AssertionError("Expected " + a + ", but got " + b);
        }
    }

    /**
     * Block until CameraManager#openCamera finishes with onOpened/onError/onDisconnected
     *
     * <p>Pass-through all StateCallback changes to the proxy.</p>
     *
     * <p>Time out after {@link #OPEN_TIME_OUT_MS} and unblock. Clean up camera if it arrives
     * later.</p>
     */
    private class OpenListener extends CameraDevice.StateCallback {
        private static final int ERROR_UNINITIALIZED = -1;

        private final String mCameraId;

        private final CameraDevice.StateCallback mProxy;

        private final Object mLock = new Object();
        private final ConditionVariable mDeviceReady = new ConditionVariable();

        private CameraDevice mDevice = null;
        private boolean mSuccess = false;
        private int mError = ERROR_UNINITIALIZED;
        private boolean mDisconnected = false;

        private boolean mNoReply = true; // Start with no reply until proven otherwise
        private boolean mTimedOut = false;

        OpenListener(CameraManager manager, String cameraId,
                CameraDevice.StateCallback listener, Handler handler)
                throws CameraAccessException {
            mCameraId = cameraId;
            mProxy = listener;
            manager.openCamera(cameraId, this, handler);
        }

        // Freebie check to make sure we aren't calling functions multiple times.
        // We should still test the state interactions in a separate more thorough test.
        private void assertInitialState() {
            assertEquals(null, mDevice);
            assertEquals(false, mDisconnected);
            assertEquals(ERROR_UNINITIALIZED, mError);
            assertEquals(false, mSuccess);
        }

        @Override
        public void onOpened(CameraDevice camera) {
            if (VERBOSE) {
                Log.v(TAG, "onOpened: camera " + ((camera != null) ? camera.getId() : "null"));
            }

            synchronized (mLock) {
                assertInitialState();
                mNoReply = false;
                mSuccess = true;
                mDevice = camera;
                mDeviceReady.open();

                if (mTimedOut && camera != null) {
                    camera.close();
                    return;
                }
            }

            if (mProxy != null) mProxy.onOpened(camera);
        }

        @Override
        public void onDisconnected(CameraDevice camera) {
            if (VERBOSE) {
                Log.v(TAG, "onDisconnected: camera "
                        + ((camera != null) ? camera.getId() : "null"));
            }

            synchronized (mLock) {
                assertInitialState();
                mNoReply = false;
                mDisconnected = true;
                mDevice = camera;
                mDeviceReady.open();

                if (mTimedOut && camera != null) {
                    camera.close();
                    return;
                }
            }

            if (mProxy != null) mProxy.onDisconnected(camera);
        }

        @Override
        public void onError(CameraDevice camera, int error) {
            if (VERBOSE) {
                Log.v(TAG, "onError: camera " + ((camera != null) ? camera.getId() : "null"));
            }

            if (error <= 0) {
                throw new AssertionError("Expected error to be a positive number");
            }

            synchronized (mLock) {
                // Don't assert initial state. Error can happen later.
                mNoReply = false;
                mError = error;
                mDevice = camera;
                mDeviceReady.open();

                if (mTimedOut && camera != null) {
                    camera.close();
                    return;
                }
            }

            if (mProxy != null) mProxy.onError(camera, error);
        }

        @Override
        public void onClosed(CameraDevice camera) {
            if (mProxy != null) mProxy.onClosed(camera);
        }

        CameraDevice blockUntilOpen() throws BlockingOpenException {
            /**
             * Block until onOpened, onError, or onDisconnected
             */
            if (!mDeviceReady.block(OPEN_TIME_OUT_MS)) {

                synchronized (mLock) {
                    if (mNoReply) { // Give the async camera a fighting chance (required)
                        mTimedOut = true; // Clean up camera if it ever arrives later
                        throw new TimeoutRuntimeException(String.format(
                                "Timed out after %d ms while trying to open camera device %s",
                                OPEN_TIME_OUT_MS, mCameraId));
                    }
                }
            }

            synchronized (mLock) {
                /**
                 * Determine which state we ended up in:
                 *
                 * - Throw exceptions for onError/onDisconnected
                 * - Return device for onOpened
                 */
                if (!mSuccess && mDevice != null) {
                    mDevice.close();
                }

                if (mSuccess) {
                    return mDevice;
                } else {
                    if (mDisconnected) {
                        throw new BlockingOpenException(
                                BlockingOpenException.ERROR_DISCONNECTED,
                                "Failed to open camera device: it is disconnected");
                    } else if (mError != ERROR_UNINITIALIZED) {
                        throw new BlockingOpenException(
                                mError,
                                "Failed to open camera device: error code " + mError);
                    } else {
                        throw new AssertionError("Failed to open camera device (impl bug)");
                    }
                }
            }
        }
    }
}