1 /*
2  * Copyright (C) 2021 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 
17 package android.hardware.camera2;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 
25 /**
26  * <p>The CameraInjectionSession class is what determines when injection is active.</p>
27  *
28  * <p>Your application must declare the
29  * {@link android.Manifest.permission#CAMERA_INJECT_EXTERNAL_CAMERA CAMERA} permission in its
30  * manifest in order to use camera injection function.</p>
31  *
32  * @hide
33  * @see CameraManager#injectCamera
34  * @see android.Manifest.permission#CAMERA_INJECT_EXTERNAL_CAMERA
35  */
36 public abstract class CameraInjectionSession implements AutoCloseable {
37 
38     /**
39      * Close the external camera and switch back to the internal camera.
40      *
41      * <p>Call the method when app streaming stops or the app exits, it switch back to the internal
42      * camera.</p>
43      */
44     @Override
close()45     public abstract void close();
46 
47     /**
48      * A callback for external camera has a success or an error during injecting.
49      *
50      * <p>A callback instance must be provided to the {@link CameraManager#injectCamera} method to
51      * inject camera.</p>
52      *
53      * @hide
54      * @see CameraManager#injectCamera
55      */
56     public abstract static class InjectionStatusCallback {
57 
58         /**
59          * An error code that can be reported by {@link #onInjectionError} indicating that the
60          * camera injection session has encountered a fatal error.
61          *
62          * @see #onInjectionError
63          */
64         public static final int ERROR_INJECTION_SESSION = 0;
65 
66         /**
67          * An error code that can be reported by {@link #onInjectionError} indicating that the
68          * camera service has encountered a fatal error.
69          *
70          * <p>The Android device may need to be shut down and restarted to restore
71          * camera function, or there may be a persistent hardware problem.</p>
72          *
73          * <p>An attempt at recovery <i>may</i> be possible by closing the
74          * CameraDevice and the CameraManager, and trying to acquire all resources again from
75          * scratch.</p>
76          *
77          * @see #onInjectionError
78          */
79         public static final int ERROR_INJECTION_SERVICE = 1;
80 
81         /**
82          * An error code that can be reported by {@link #onInjectionError} indicating that the
83          * injection camera does not support certain camera functions. When this error occurs, the
84          * default processing is still in the inject state, and the app is notified to display an
85          * error message and a black screen.
86          *
87          * @see #onInjectionError
88          */
89         public static final int ERROR_INJECTION_UNSUPPORTED = 2;
90 
91         /**
92          * @hide
93          */
94         @Retention(RetentionPolicy.SOURCE)
95         @IntDef(prefix = {"ERROR_"}, value =
96                 {ERROR_INJECTION_SESSION,
97                         ERROR_INJECTION_SERVICE,
98                         ERROR_INJECTION_UNSUPPORTED})
99         public @interface ErrorCode {};
100 
101         /**
102          * The method will be called when an external camera has been injected and replaced
103          * internal camera's feed.
104          *
105          * @param injectionSession The camera injection session that has been injected.
106          */
onInjectionSucceeded( @onNull CameraInjectionSession injectionSession)107         public abstract void onInjectionSucceeded(
108                 @NonNull CameraInjectionSession injectionSession);
109 
110         /**
111          * The method will be called when an error occurs in the injected external camera.
112          *
113          * @param errorCode   The error code.
114          * @see #ERROR_INJECTION_SESSION
115          * @see #ERROR_INJECTION_SERVICE
116          * @see #ERROR_INJECTION_UNSUPPORTED
117          */
onInjectionError(@onNull int errorCode)118         public abstract void onInjectionError(@NonNull int errorCode);
119     }
120 
121     /**
122      * To be inherited by android.hardware.camera2.* code only.
123      *
124      * @hide
125      */
CameraInjectionSession()126     public CameraInjectionSession() {
127     }
128 }
129