/* * 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. * *

Safe to use at the same time as the regular CameraManager, so this does not * duplicate any functionality that is already blocking.

* *

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.

*/ 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. * *

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.

* *

Throws {@link CameraAccessException} for the same reason {@link CameraManager#openCamera} * does.

* *

Throws {@link BlockingOpenException} when the open fails asynchronously (due to * {@link CameraDevice.StateCallback#onDisconnected(CameraDevice)} or * ({@link CameraDevice.StateCallback#onError(CameraDevice)}.

* *

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.

* * @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 * *

Pass-through all StateCallback changes to the proxy.

* *

Time out after {@link #OPEN_TIME_OUT_MS} and unblock. Clean up camera if it arrives * later.

*/ 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)"); } } } } } }