1/*
2 * Copyright (C) 2013 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.camera2;
18
19import android.annotation.NonNull;
20import android.annotation.IntDef;
21import android.util.AndroidException;
22
23import java.lang.annotation.Retention;
24import java.lang.annotation.RetentionPolicy;
25
26/**
27 * <p><code>CameraAccessException</code> is thrown if a camera device could not
28 * be queried or opened by the {@link CameraManager}, or if the connection to an
29 * opened {@link CameraDevice} is no longer valid.</p>
30 *
31 * @see CameraManager
32 * @see CameraDevice
33 */
34public class CameraAccessException extends AndroidException {
35    /**
36     * The camera device is in use already.
37     */
38    public static final int CAMERA_IN_USE = 4;
39
40    /**
41     * The system-wide limit for number of open cameras or camera resources has
42     * been reached, and more camera devices cannot be opened or torch mode
43     * cannot be turned on until previous instances are closed.
44     */
45    public static final int MAX_CAMERAS_IN_USE = 5;
46
47    /**
48     * The camera is disabled due to a device policy, and cannot be opened.
49     *
50     * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean)
51     */
52    public static final int CAMERA_DISABLED = 1;
53
54    /**
55     * The camera device is removable and has been disconnected from the Android
56     * device, or the camera id used with {@link android.hardware.camera2.CameraManager#openCamera}
57     * is no longer valid, or the camera service has shut down the connection due to a
58     * higher-priority access request for the camera device.
59     */
60    public static final int CAMERA_DISCONNECTED = 2;
61
62    /**
63     * The camera device is currently in the error state.
64     *
65     * <p>The camera has failed to open or has failed at a later time
66     * as a result of some non-user interaction. Refer to
67     * {@link CameraDevice.StateCallback#onError} for the exact
68     * nature of the error.</p>
69     *
70     * <p>No further calls to the camera will succeed. Clean up
71     * the camera with {@link CameraDevice#close} and try
72     * handling the error in order to successfully re-open the camera.
73     * </p>
74     *
75     */
76    public static final int CAMERA_ERROR = 3;
77
78    /**
79     * A deprecated HAL version is in use.
80     * @hide
81     */
82    public static final int CAMERA_DEPRECATED_HAL = 1000;
83
84     /** @hide */
85     @Retention(RetentionPolicy.SOURCE)
86     @IntDef(
87         {CAMERA_IN_USE,
88          MAX_CAMERAS_IN_USE,
89          CAMERA_DISABLED,
90          CAMERA_DISCONNECTED,
91          CAMERA_ERROR})
92     public @interface AccessError {};
93
94    // Make the eclipse warning about serializable exceptions go away
95    private static final long serialVersionUID = 5630338637471475675L; // randomly generated
96
97    private final int mReason;
98
99    /**
100     * The reason for the failure to access the camera.
101     *
102     * @see #CAMERA_DISABLED
103     * @see #CAMERA_DISCONNECTED
104     * @see #CAMERA_ERROR
105     */
106    @AccessError
107    public final int getReason() {
108        return mReason;
109    }
110
111    public CameraAccessException(@AccessError int problem) {
112        super(getDefaultMessage(problem));
113        mReason = problem;
114    }
115
116    public CameraAccessException(@AccessError int problem, String message) {
117        super(getCombinedMessage(problem, message));
118        mReason = problem;
119    }
120
121    public CameraAccessException(@AccessError int problem, String message, Throwable cause) {
122        super(getCombinedMessage(problem, message), cause);
123        mReason = problem;
124    }
125
126    public CameraAccessException(@AccessError int problem, Throwable cause) {
127        super(getDefaultMessage(problem), cause);
128        mReason = problem;
129    }
130
131    /**
132     * @hide
133     */
134    public static String getDefaultMessage(@AccessError int problem) {
135        switch (problem) {
136            case CAMERA_IN_USE:
137                return "The camera device is in use already";
138            case MAX_CAMERAS_IN_USE:
139                return "The system-wide limit for number of open cameras has been reached, " +
140                       "and more camera devices cannot be opened until previous instances " +
141                       "are closed.";
142            case CAMERA_DISCONNECTED:
143                return "The camera device is removable and has been disconnected from the " +
144                        "Android device, or the camera service has shut down the connection due " +
145                        "to a higher-priority access request for the camera device.";
146            case CAMERA_DISABLED:
147                return "The camera is disabled due to a device policy, and cannot be opened.";
148            case CAMERA_ERROR:
149                return "The camera device is currently in the error state; " +
150                       "no further calls to it will succeed.";
151        }
152        return null;
153    }
154
155    private static String getCombinedMessage(@AccessError int problem, String message) {
156        String problemString = getProblemString(problem);
157        return String.format("%s (%d): %s", problemString, problem, message);
158    }
159
160    private static String getProblemString(int problem) {
161        String problemString;
162        switch (problem) {
163            case CAMERA_IN_USE:
164                problemString = "CAMERA_IN_USE";
165                break;
166            case MAX_CAMERAS_IN_USE:
167                problemString = "MAX_CAMERAS_IN_USE";
168                break;
169            case CAMERA_DISCONNECTED:
170                problemString = "CAMERA_DISCONNECTED";
171                break;
172            case CAMERA_DISABLED:
173                problemString = "CAMERA_DISABLED";
174                break;
175            case CAMERA_ERROR:
176                problemString = "CAMERA_ERROR";
177                break;
178            case CAMERA_DEPRECATED_HAL:
179                problemString = "CAMERA_DEPRECATED_HAL";
180                break;
181            default:
182                problemString = "<UNKNOWN ERROR>";
183        }
184        return problemString;
185    }
186
187}
188